(Difference between revisions)
|
|
| Line 3: |
Line 3: |
| | = Start from a known state = | | = Start from a known state = |
| | | | |
| - | A guide should start from a known state and explain to the reader what that state is. For example: | + | A guide should explain why it exists: |
| - | | + | |
| - | * A "getting started" tutorial should start from a clean install of an operating system.
| + | |
| - | * A tutorial about "advanced widget use" might build from a state reached in a previous tutorial. But you need to make that explicit: say, "You should do tutorial X before you start this tutorial"
| + | |
| - | | + | |
| - | A guide should also explain why it exists:
| + | |
| | | | |
| | * What it will show you to do (build a PDF viewer, understand how DBus works) | | * What it will show you to do (build a PDF viewer, understand how DBus works) |
| | * The intended audience (beginner, C programmer, web programmer) | | * The intended audience (beginner, C programmer, web programmer) |
| | * The vertical it's applicable for (will it only work for netbooks?) | | * The vertical it's applicable for (will it only work for netbooks?) |
| | + | |
| | + | A guide should start from a known state and explain to the reader what that state is. For example: |
| | + | |
| | + | * A "getting started" tutorial should start from a clean install of an operating system. |
| | + | * A tutorial about "advanced widget use" might build from a state reached in a previous tutorial. But you need to make that explicit: say, "You should do tutorial X before you start this tutorial" |
| | | | |
| | = Tell a story = | | = Tell a story = |
Revision as of 16:53, 6 May 2010
Some guidelines for writing MeeGo (well, any) kind of developer documentation.
Start from a known state
A guide should explain why it exists:
- What it will show you to do (build a PDF viewer, understand how DBus works)
- The intended audience (beginner, C programmer, web programmer)
- The vertical it's applicable for (will it only work for netbooks?)
A guide should start from a known state and explain to the reader what that state is. For example:
- A "getting started" tutorial should start from a clean install of an operating system.
- A tutorial about "advanced widget use" might build from a state reached in a previous tutorial. But you need to make that explicit: say, "You should do tutorial X before you start this tutorial"
Tell a story
Explain too much, rather than too little
Compare the new with the familiar
Provide useful, relevant, meaningful code samples
Code examples should be:
- Self-contained (as far as possible): you should be able to compile them without needing loads of tools, or use them straight away inside an IDE like Qt Creator. If this isn't impossible, they should include a README or INSTALL document explaining how to build them.
- Meaningful: they should provide a solution for some possible issue. For example, if you're explaining how to use widgets, write an application which demonstrates how to use them in context, e.g. an address book.
- Included in the MeeGo code examples repository: ???no URL yet??? This makes it easier for other people to get at them, fix them, extend and improve them.
- Available under a liberal open source licence. I suggest BSD.
Some open problems:
- How to include source code in guides. I tend to cut and paste as I go, but maybe there's a better way.
Don't get sidetracked