Comparing GUI app documentation with web documentation

Is documentation for a GUI app different from documentation for a web site? That's a curly question someone asked me recently.

I only considered the documentation in the completed app or web page, not documentation for the development process. Alas, my thinking did not produce any great new truths.

I believe there are no profound differences. The problem is that most people don't understand the requirements for good web content, so that statement isn't very enlightening! Here are some tips from my perspective. They're general points, but I'd give them priority.

• Write for non-technical people who use the app or page, not for your peers, and don't use jargon.
• Be as brief as possible. The more you explain, the less people remember—literally.
• Put the explanations right where people need them most, in their face.
• Use conversational language but keep it brief and use standard terms, not slang: your audience is probably international, even if they all live in the same country as you do.
• Use the active voice and the word 'you'. Talk to the user, not about the problem.
• When giving a series of instructions, put them in order and number them.
• Separate items of information clearly. Say only what's necessary in each case.

And enjoy your work!

The Thinker, sculpture by Auguste Rodin. Picture taken in Musee Rodin in Paris, France by Pufacz.