PrevKDE Writing Recommendations and GuidelinesNext

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.

    Note

    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.