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