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