PrevKDE Writing Recommendations and GuidelinesNext

Writing Well

Some things to think about when writing documentation

How many times have you attempted to read a man page, and given up in frustration — all the facts are there, but the writing is too dry and technical for you to make sense of them? We want to avoid this with the documentation you are writing.

It is difficult to avoid the very dry, choppy style we're all too familiar with, but do try to make the writing flow and keep it user-friendly. Try to be as friendly as you can manage without being patronizing, and without sacrificing clarity or detail.

Things you should consider:

  • Make sure you explain all aspects of the interface, and that you do not leave out any command line options available.

  • It is important to keep a logical progression of difficulty. Keep the first few pages of the document simple, and accessible to users who have never seen the application before. More technical information should appear towards the end of the document.

  • Be sure to write to the level of the intended reader. By this we mean, a Samba control module has a very different user base than a user of a game, and the manuals should reflect this. Do not insult the Samba networker's intelligence, and do not assume knowledge for the gamer that might not be there.

  • It is highly encouraged to use screenshots, pictures of action buttons, etc. These are GUI applications, and a picture can be worth a thousand words.

  • Please define computer abbreviations, unless they are well understood by all computer users (There's no need to define RAM, PC, etc.).

    For example, “If you are going to use PPP (Point to Point Protocol), then.....”. Define it only once though, in this example you could now use PPP without explanation for the rest of the document.

    The first time you introduce the word you should use <firstterm> or consider setting up a glossary and using <glossentry>.

  • Remember the small things: If it is dockable, explain how to do that. Do not forget to mention where it installs itself in the K menu. If there are any environment settings required, and if they must be set manually, explain how to do that - if they're set automatically, they still need to be documented.

  • Write something you would be happy to read as a user who doesn't know how the application works. Perhaps if you have a friend or family member who isn't familiar with the application you are writing about, have them work through using it, with your documentation as a guide.