Some guidelines for writing MeeGo (well, any) kind of developer documentation.
A guide should explain why it exists:
A guide should start from a known state and explain to the reader what that state is. For example:
Start with small pieces and join them into a significant whole. Make sure there's a progression (from nothing to something).
Only add a small amount at each step, and make sure what you add is one coherent thing: for example, implement a single feature or explain a single concept (that's tricky to work out...).
You could show a screenshot of the finished application and then say "here's how we got here". But don't start with a big pile of code and try to pick it apart and explain it. That's difficult for someone to grasp.
If you're writing about building a full application, add the features in a logical order the way a developer might do it, e.g.
Make sure there is a reason for adding each new feature. Adding spurious, unrealistic, disjointed (but maybe cool) features doesn't make a good story.
You could also use "characters" and put them in scenarios which mirror development in the real world. For example:
The O'Reilly Head First books are a good example of how to do this well
While writing, imagine you're explaining to a peer, colleague, family member or friend (depending on the type of audience you're writing for). This makes your writing more natural and help you get the flow right: it's easier to track a conversation in your head than it is to track an abstract explanation.
Use "we" and "you", to address the reader. Compare the following two pieces of text and see which one reads better:
The button widget can be added to a layout using the add_actor method.
You can add a button widget to a layout using the add_actor method.
(I'd argue the second reads better.)
Explain concepts by getting the reader to carry out a task related to them. Rather than explaining about something in abstract, show the reader what "impact" it will have on them: what effect it has on the application, or on their programming skill, or on the world around them (more generally).
This means someone knows what they're going to achieve by the end of the section, and has an idea of the scope of the information in that section.
Try not to make too many assumptions about the reader
Code examples should be:
Some open problems: