Revision as of 08:26, 2 September 2012
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 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. 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.
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?"
- User Guide
- A much higher level overview of KDE and its applications. This aims to be the first stop for users to look for information, and should be task based.
When writing for the User Guide, 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 this guide do not have an actual problem, they simply want to achieve a goal, and don't yet know how, or where to find that information.
The User Guide should be answering the question: "How do I do this common task, eg send an email, play a movie?"
- 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?"
English Usage Guidelines and Recommendations
KDE documentation is written in standard US English (rather than any other regional variety of English). We have a set of standard forms of certain words (such as "email" instead of "e-mail") to improve consistency across all documentation. There are also standard names for KDE widgets, which are listed in Appendix B. A Visual Guide
A good way to catch simple errors is to read the text out loud, or have someone else read it to you. Passages that don't flow easily or have obviously awkward construction of the type you may miss on the screen, will usually become blindingly obvious when you hear them. This is especially the case with detecting really long sentences, as you will run out of breath and turn blue.
Some tips about writing readable sentences:
- Use complete sentences. Not fragments. Like these ones.
- Avoid run-on sentences, sentences that cover several different subjects, or sentences that could be broken up into several sentences; avoid sentences that can fill a whole paragraph all by themselves and that are really long, like this one, which is all of the above.
Use a comma before "and" in compound sentences, eg "Use the left mouse button to select and copy text, and the middle mouse button to paste it."
- Try not to use the same word several times in the same sentence. An exception to this, is an application command or technical word, where this repetition is necessary, and improves clarity.
- Do not start sentences with any of "and," "so," "but, "because," or "however."
- Try to avoid contractions, rather spell out both words; eg, "it is" rather than "it's"; "can not" rather than "can't"
- There is no need to worry about simple text formatting such as leaving two spaces after punctuation or indenting paragraphs. This is all handled by DocBook XML and the XSLT stylesheets in use.
Remember, we have also an active proofreading team, and there is always someone to help you with grammar, so just write and have fun!
What to Include
For most applications, a structure something like this would be appropriate:
- Introduction: A basic description of what the application does and any noteworthy features, etc.
- Using KApp: Task-based description of the most common uses of the application.
- Program reference: Description of all of the features of the application.
This would usually include a menu reference, but might also include command line options, syntax description, etc, if they are appropriate to the application. This is required for all KDE applications that you at a minimum cover any application specific menu entries, and strongly recommended that you cover all the standard ones too (in case users are reading the manual outside of KDE, or yours happens to be the first one they read, and it provides consistency. Cut and paste is your friend here.)
Note that although this is a required section, and for some applications it is the only section, it should be considered a minimum.
- Frequently Asked Questions: List the most common questions and problems that users have with the application, and their solutions. "How do I ...?"-type questions are especially appropriate.
- Credits and License: A list of those who contributed to the documentation, and a link to the GNU Free Documentation License, under which all KDE documentation is licensed. This chapter is required for all KDE documents, and must have at least the two license links (one for the document, and one for the application)
- Installation: This chapter can be automatically generated, provided that the application follows the usual KDE compilation procedure. If you need to add extra information about compiling or installing the application, it can go here.
You will find a template document with these sections in template.docbook file in KDE git repository.