English Usage Guidelines and RecommendationsKDE 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!