Some tips for writing MeeGo (well, any) kind of documentation. These are based on my personal experience (I've been a technical author and written two books, as well as many presentations, essays, articles etc.).

Note that this is a work in progress (I hypocritically haven't followed my own guidelines :) ), so should improve over time.

Contents 1 Start from a known state 2 Tell a story 3 Write conversationally and informally 4 Use task-based structures 5 Explain too much, rather than too little 6 Compare the new with the familiar 7 Provide useful, relevant, meaningful code samples 8 Don't get sidetracked 9 Leave a gap between drafts

Start from a known state

You should explain why the document 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?)

Also explain any assumptions you're making about the reader and their context. 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".
• A programming tutorial should either tell the reader what they need to install, or tell them where to find that out, or tell them they should go and work it out for themselves.

You can be explicit about where a MeeGo document belongs by categorising it: I put some suggestions about how to do this in Developer_guide_content_organisation.

Tell a story

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 at each step is a coherent unit: for example, implement a single feature or explain a single concept. (Though working out how big a unit should be is tricky in itself.)

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.

1. Set up the project
2. Create the basic skeleton of the application
3. Add some read-only widgets
4. Add behaviour to the widgets but stub out interactions with other parts of the environment
5. Add interactions with the real environment (e.g. fetch data from the network, talk to device APIs)

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:

• A developer is being asked by a customer to add new features to an application.
• A tester and developer are working together on testing an application.
• A developer is writing an application for his girlfriend.

The O'Reilly Head First books are a good example of how to do this well

Write conversationally and informally

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"; address the reader directly. 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.)

Use task-based structures

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).

For example:

• "Configuring the application" rather than "Application configuration"
• "Writing a depth-first parser" rather than "Depth-first parser construction"
• "Adding a label widget" rather than "Label widgets"

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.

Explain too much, rather than too little

Try to make the right assumptions about the reader, what they know, and the context they're working in. Having a fictional conversation with someone real helps with this, as you can use what you know about that person to decide what to explain. For example:

• If I'm writing a beginner programming tutorial, I imagine I'm talking to one of my friends or family, who understands computers (they know what a menu is, how to select things, understand OK and Cancel buttons), but not so much about programming.
• If I'm writing about an advanced programming topic, I imagine I'm talking to one of my co-workers. I have a decent idea of their field of reference: they'll know what the Model View Controller pattern is, understand what a method signature is, be familiar with how network protocols work. At the same time, I might think "I've probably done more web programming than they have, so they may not be so familiar with CSS and HTML syntax" etc..

Each time you feel the need to explain something, decide whether that person would already know it. If you're not sure, explain it.

Compare the new with the familiar

This relates to the previous section: if you're explaining something new, compare it to something the reader might already know about. Some of the time, if it's new to you, this can help you find a way to understand it yourself, too.

As an example, a few months back I helped write a page about DBus. There was a section about signals, but I wasn't really getting how to use them, and felt this would hinder other people understanding it, too. So I tried to find an explanation of signals which related to the real world, and came up with this:

Signals provide a way for objects to notify other objects about events which happen to them: for example, a Door interface might provide a signal to other objects when it is opened, perhaps called door-opened. (A nearby Doorman object might listen out for door-opened signals, so it knows when people come into the building.)

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 possible, 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

Try to stay focused on the topic. This sounds obvious, but it's sometimes difficult to resist "showing off". Just because the history of compilers is very interesting, it doesn't mean you should cover it in a tutorial about writing desktop applications.

Leave a gap between drafts

Write a first draft, then leave it alone for a few hours (preferably 24).

Then go back to it and read it over from start to finish, correcting as you go. Because you've had a break from what you've written, you'll be able to look more objectively at it, and be able to spot errors or places where the "flow" isn't right.

Don't be afraid to restructure. Look for sections you can reduce in size or remove.