Chapter 3. KDE Writing Recommendations and Guidelines

To maintain a uniform documentation set, there are some consistency rules to be followed, that you should know before starting. In this chapter you will find guidelines about targeting your audience, english usage, and what to cover when you are documenting an application.

We also offer some general writing tips to help you to get started, provided by experienced KDE documenters.

Writing for your Audience

Since KDE is used by people with a wide range of abilities, from completely new users to long-time gurus, the documentation should be appropriate to this audience. Therefore, in general, documentation shouldn't assume too much about the knowledge of the reader, without being patronising. There are no hard-and-fast rules, but here are some tips that should help:

  • Remember that the audience varies with the application: for example, a server control module has a very different user base than a user of a game, and the manuals should reflect this. Don't insult the administrator intelligence, and don't assume knowledge for the gamer that might not be there.

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