KDE Writing Recommendations and GuidelinesTo 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.
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 patronizing. 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. Do not insult the administrator intelligence, and do not 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.
Remember also that different types of documentation have different purposes:
- Application Handbooks
These may go into great depths on the configuration, behavior and sometimes the philosophy of an application. There is scope to cover corner cases of configuration, commonly asked questions, and advanced troubleshooting techniques.
They should also always contain a complete reference to all the available menu functions and configuration options for the application (but while these are required, they should be certainly be considered a minimum of information to provide.)
The Application Handbook should be answering the question: “What are all the things I can do with this application?”
- Fundamentals
A much higher level overview of KDE. This aims to be the first stop for users to look for information, and should be task based.
When writing for the Fundamentals, you should assume a working default installation of KDE, and you do not need to cover all cases of unusual configurations, only the very common variations, nor should you cover in-depth troubleshooting. You might provide answers to some very common configuration errors (or not, as appropriate) and refer to the Application Manual, the Application's Website, mailing list, and any appropriate man pages for more detailed information.
Most people reading these Fundamentals do not have an actual problem, they simply want to achieve a goal, and do not yet know how, or where to find that information.
- What's This Help
A very focused and specific type of assistance, about a single configuration or interface item. Again you should not really attempt to cover all cases here, only common ones, and explain what the option does, not why it is there. Refer users to the Application Handbook if appropriate, for more information.
Provide an example of the expected input, if that is not clear from the context.
The What's This Help is most often answering the question: “Do I need to fill in this box? If so, what do I put in it?”