Sunday, 4 August 2019 | The KDE Documentation Team

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. 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?"

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. Work is underway to expand and formalize this list, but for the moment, it is located at Preferred forms. There are also standard names for KDE widgets, which are listed in the Visual Dictionary.

A good way to catch simple errors is to read the text out loud, or have someone else read it to you. Passages that do not 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, e.g. "Use the left mouse button to select and copy text, and the middle mouse button to paste it."
Keep to logical sentence order.

For example, "Konqueror is a web browser with the ability to browse file systems and it includes a javascript interpreter." (Do you see why this is awkward?)
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; e.g., "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 also have 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 could include a menu reference, but might also include command line options, syntax description, etc., if they are appropriate to the application.

This chapter should list all of the application windows and their menubar and toolbar commands for easy reference. Also include any keys that have a special function but have no equivalent in the menus or toolbars. This may not be necessary for small apps or apps with no tool or menu bars. Link to default menuitems in the Fundamentals.
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)

You will find a template document with these sections in template docbooks in the KDE Git repository.

Consistency

Dates

While it may seem like a minor issue, and a minor part of your document, it is very important that the following guidelines are adhered to:

All dates which are part of the text of your document should be spelled out i.e. "March 2, 2000"

This is the only way to be sure that "03/02/2000" is interpreted correctly in all languages, and by all readers.

Important exception: in the date tag, dates should be in the "YYYY-MM-DD" format.

Other Consistency Issues

Please submit only plain ASCII text, AsciiDoc document format or Docbook XML. Anything else will be returned to you. (Docbook XML is preferred.)
Make sure you first read, and follow, the documentation template provided. You can find this in the source folder for kdoctools. Simply point a browser to template.docbook in the KDE Git repository.

If there is existing documentation, then use that as a base to work from, but it needs to conform to the layout from the newest documentation template.
Spell things according to Standard American spelling, except for proper names, places, etc.
Make sure to set your spellchecker to US English. Make sure you use your spellchecker.
If there is a non-English word, which is used in an English sentence, be sure to spell this correctly, using appropriate accent marks, and any special characters. Use the KCharSelect application if you do not have the correct keys on your keyboard.
Abbreviations should be capitalized, unless they are specifically intended to not be capitalized. (i.e. is a good example).
Punctuation within numbers should be Americanized: 10,000.00
It is more legible to use written numbers where the number has no technical value, e.g. "There are three buttons on the dialog". In this context "3" is not technically significant. Numbers with technical significance should be written as figures. (i.e. "a 10 MB file", not "a ten MB file".)
Spellcheck and proofread your work before you send it in. Or even better, have someone else read it over. Spellchecking programs won't catch incorrect words such as using "their" for "there".

Use aspell -d en_US --add-filter=sgml -c path/to/index.docbook in a Konsole.

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.

Resources

General Purpose Websites

A few sites you may find worth bookmarking, or at least visiting.

Dictionary Sites

Thesaurus Sites

Merriam-Webster have a thesaurus as well as a dictionary
Thesaurus and Dictionary

Style Guides and Other Resources

Strunk & White is the base style guide for many newspapers and press galleries. If you want to look up a grammar or usage question, this is the place to go.
The alt.usage.english newsgroup. If you'd like every sentence chewed over, dissected, and then rewritten several conflicting ways, or some great advice about bacon, you will find both here. Many real live editors and authors hang out here, and they do know their stuff. Just make sure you read all ten or so FAQ's before asking a question.

Article contributed by Yuri Chornoivan, Burkhard Lück, Nicolas Ternisien, and Carlos Woelz under the GFDL-1.2-or-later license.

KDE Writing Recommendations and Guidelines - The KDE Documentation Primer