Revision as of 16:57, 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:

• 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.
• 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 an INSTALL file (or at least README comments) explaining how to build them, distributed with the code (see above).
• 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.
• 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

???