Documentation/Use case template

On documenting use cases

  • Use case pages are open. Anybody can fix/improve/extend/link them. Anybody can create new use cases.
  • Use cases are grouped under the domain to which they are related, as follows: Maemo Developer Guide/<Domain>/<Use Case>.
  • Add use case name as the title of the page.
  • Write the use case name as follows, with the verb in the -ing format <Playing a video clip with your application>
  • Write the use case from the developer's point of view. That is, write how to complete this task/solve this problem instead of how to use this functionality.
  • Fill in all sections marked as mandatory. Do not delete the headings of mandatory sections.
  • If you cannot think of any information that should be added in an optional section, you can delete the heading of the section.
  • Add the following wikitext on the use case page to import this template: 
{{subst::Documentation/Use_Case_template}}
###This is a mandatory section.###
Describe the objective of the developer. 
Remember that one use case only answers one question, such as "How to display a list of media files?" 
or "How to play the media files selected by a device user?".
In contrast, the API doc explains the functionality from a platform point of view.

Contents

[edit] Prerequisites 

###This is a mandatory section.###
Briefly describe the previous steps and knowledge needed to get to this point.
Do not state the obvious, such as "SDK installed" or "C++ knowledge". 
Link to any logical previous steps documented in the Developer Library or elsewhere.
If there are no prerequisites for the use case, write "There are no prerequisites for this use case." in this section.

[edit] Related APIs 

###This is a mandatory section.###
Present the set of APIs used in this use case and describe them in general. 
(Related APIs can also come from other areas than the one under which the use case is placed.)
Link to API docs.

[edit] Steps 

###This is a mandatory section.###
Provide numbered step-by-step instructions on how to complete the task.
Include relevant code snippets and screenshots to help the reader understand the steps.

1. <Do this-and-this>

<An example code snippet>

2. <Do that-and-that>

<An example code snippet>

[edit] Examples 

###This is a mandatory section.###
Link to code examples at http://maemo.gitorious.org (default) and/or other relevant code repositories.
Link to Maemo open source applications that provide good examples related to this use case.

[edit] Further actions 

###This is an optional section.###
Link to any logical next steps documented in the Developer Library or elsewhere.

[edit] Tips & Tricks 

###This is a mandatory section, but leave its contents blank.###
In this section readers can share their own learnings & interesting links.
  • Your tip here.
Retrieved from "http://wiki.maemo.org/Documentation/Use_case_template"