diff options
Diffstat (limited to 'doc/tutorials/styleguide/index.docbook')
| -rw-r--r-- | doc/tutorials/styleguide/index.docbook | 466 |
1 files changed, 466 insertions, 0 deletions
diff --git a/doc/tutorials/styleguide/index.docbook b/doc/tutorials/styleguide/index.docbook new file mode 100644 index 0000000..8c94356 --- /dev/null +++ b/doc/tutorials/styleguide/index.docbook @@ -0,0 +1,466 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kde-authors '<personname><surname>The &kde; Documentation Team</surname></personname>'> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"><!-- change language only here --> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &tde; Style Guide</title> + +<authorgroup> +<author>&kde-authors;</author> +<author>&tde-authors;</author> +</authorgroup> + +<copyright> +<year>2002</year> +<holder>The KDE e.V.</holder> +</copyright> +<copyright> +<year>&tde-copyright-date;</year> +<holder>&tde-team;</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>&tde-release-date;</date> +<releaseinfo>&tde-release-version;</releaseinfo> + +<abstract> +<para> +A reference guide to &tde; style standards for writing documentation. +Please report any errors or omissions to +<email>[email protected]</email>. +</para> +</abstract> + +<keywordset> +<keyword>TDE</keyword> +<keyword>Docbook</keyword> +<keyword>Documentation</keyword> +<keyword>Authors</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para>The purpose of writing documentation for the &tde; Project, is +to create for all the users, a complete, well organized set of +documentation for each and every component of the &tde; project. In +order to achieve this goal, we have drafted the following guide to +help.</para> + +<para>This document is very new, and at the moment, very +sparse.</para> + +<para>If you have comments or additions, please do not hesitate to +suggest them on the [email protected] mailing list.</para> + +<para>In the meantime, here are some short notes based on content that +was previously on the <ulink url="http://i18n.kde.org/">&tde; +i18n</ulink> website.</para> + +</chapter> + +<chapter id="consistency"> +<title>Consistency</title> + +<sect1 id="dates-and-revisions"> +<title>Dates and Revision Numbers</title> + +<para>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:</para> + +<itemizedlist> +<listitem> +<para>All dates which are part of the text of your document +should be spelled out &ie; <quote>March 2, 2000</quote></para> +<para>This is the only way to be sure that <quote>03/02/2000</quote> +is interpreted correctly in all languages, and by all readers.</para> +<important><para>Exception: in the <sgmltag>date</sgmltag> tag, dates +should be in the <quote>YYYY-MM-DD</quote> format.</para> +</important> +</listitem> +<listitem> +<para>All information included between the <sgmltag +class="starttag">releaseinfo</sgmltag> and <sgmltag +class="endtag">releaseinfo</sgmltag> should match the release number +of the application.</para> +</listitem> +</itemizedlist> +</sect1> + +<sect1 id="screenshots"> +<title>Screenshot Consistency</title> + +<para>To create consistent screenshots, use an environment where all requirements can +be configured without interfering with your normal production environment. One option +is a virtual machine. Another option is creating at least two themes. One theme is the +normal everyday theme for production. The other theme is for handbook screenshots. +Toggle between the two themes as necessary. A third option is a separate user +account configured as required.</para> + +<para>To strive for a look of consistency with screenshots, please abide by the +following requirements.</para> + +<itemizedlist> + +<listitem> +<para>No personal information. That includes login names. Be careful when including +window decorations because the title bar could include such information. Use a testing +account or a virtual machine when such information cannot be avoided.</para> +</listitem> +<listitem> +<para>Use &ksnapshot;. Normally use the <guilabel>Window Under Cursor</guilabel> option. Use the +<ulink url="help:/ksnapshot"> &ksnapshot; Handbook</ulink> to learn more.</para> +</listitem> +<listitem> +<para>Using the &ksnapshot; <guilabel>Include window decorations</guilabel> option is not +required and not forbidden. Just ensure the decorations to do not interfere with the +purpose of the screenshot.</para> +</listitem> +<listitem> +<para>PNG images only.</para> +</listitem> +<listitem> +<para>Window decorations: KDE2, Keramik, or Plastik.</para> +</listitem> +<listitem> +<para>Widget style: KDE Classic, Keramik, or Plastik.</para> +</listitem> +<listitem> +<para>In &kcontrol;->Style, enable <guilabel>Show icons on buttons</guilabel>.</para> +</listitem> +<listitem> +<para>Colors: TDE defaults.</para> +</listitem> +<listitem> +<para>Background: No wallpaper, no gradients.</para> +</listitem> + +</itemizedlist> + +</sect1> + +<sect1 id="other-consistency-issues"> +<title>Other Consistency Issues</title> + +<itemizedlist> +<listitem> +<para>Please submit only plain <acronym>ASCII</acronym> text, or +Docbook &XML;. Anything else will be returned to you. (Docbook &XML; is +preferred.)</para> +</listitem> +<listitem> +<para>Make sure you first read, and follow, the documentation template +provided. You can find this in the source folder for &tde;. Simply +point a browser to <filename +class="directory">tdelibs/doc/kdoctools/template.docbook</filename></para> +<note><para>If there is existing documentation (from the developer, or +from &tde; 1.x or 2.x), then use that as a base to work from, but it +needs to conform to the layout from the documentation +template.</para></note> +</listitem> +<listitem> +<para>Spell things according to Standard American spelling, except for +proper names, places, &etc;</para> +</listitem> +<listitem> +<para>Make sure to set your spell checker to US English. Make sure you +<emphasis>use</emphasis> your spell checker.</para> +</listitem> +<listitem> +<para>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 don't have the correct keys on your keyboard.</para> +</listitem> +<listitem> +<para>Abbreviations should be capitalized, unless they are +specifically intended to not be capitalized. (&ie; is a good +example).</para> +</listitem> +<listitem> +<para>Punctuation within numbers should be Americanized: +10,000.00</para> +</listitem> +<listitem> +<para>It is more legible to use written numbers where the number has +no technical value, ⪚ <quote>There are three buttons on the +dialog</quote>. In this context <quote>3</quote> is not technically +significant. Numbers with technical significance should be written as +figures. (&ie; <quote>a 10 MB file</quote>, not <quote>a ten MB +file</quote>.)</para> +</listitem> +<listitem> +<para>Spell check and proofread your work before you send it in. Or +even better, have someone else read it over. Spell checking programs +won't catch incorrect words such as using <quote>their</quote> for +<quote>there</quote>.</para> +</listitem> +</itemizedlist> +</sect1> + +</chapter> + +<chapter id="writing-well"> +<title>Writing Well</title> + +<para>Some things to think about when writing documentation</para> + +<para>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're writing. </para> + +<para>It's 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 +<emphasis>user-friendly</emphasis>. Try to be as friendly as you can +manage without being patronizing, and without sacrificing clarity or +detail.</para> + +<para> Things you should consider: </para> + +<itemizedlist> + +<listitem> +<para>Make sure you explain all aspects of the interface, and that you +don't leave out any command line options available. </para> +</listitem> + +<listitem> +<para>It's 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. </para> +</listitem> + +<listitem> +<para>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. Don't insult the +Samba networker's intelligence, and don't assume knowledge for the +gamer that might not be there.</para> +</listitem> + +<listitem> +<para>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. </para> +</listitem> + +<listitem> +<para>Please define computer abbreviations, unless they are well +understood by all computer users (There's no need to define +<acronym>RAM</acronym>, <acronym>PC</acronym>, &etc;).</para> + +<para>For example, <quote>If you are going to use +<acronym>PPP</acronym> (Point to Point Protocol), +then.....</quote>. Define it only once though, in this example you +could now use <acronym>PPP</acronym> without explanation for the rest +of the document.</para> + +<para>The first time you introduce the word you should use <sgmltag +class="starttag">firstterm</sgmltag> or consider setting up a glossary +and using <sgmltag class="starttag">glossentry</sgmltag>.</para> +</listitem> + +<listitem> +<para>Remember the small things: If it's dockable, explain how to do +that. Don't 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.</para> +</listitem> + +<listitem> +<para>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're writing about, +have them work through using it, with your documentation as a +guide. </para> +</listitem> +</itemizedlist> + +</chapter> + +<chapter id="more-hints"> +<title>Other general tips and hints for good writing</title> + +<para>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 +<quote>flow</quote> 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.</para> + +<para>Be concise, be specific, and be direct. Choose your words +carefully, and be certain you know the exact meaning of every word +you use. Is it the right word? Use a dictionary, and find out.</para> + +<para>Use complete sentences. Not fragments. Like these ones.</para> + +<para>While talking about sentences:</para> +<itemizedlist> +<listitem> +<para>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.</para> +</listitem> +<listitem> +<para> +Use a comma before <quote>and</quote> in compound sentences, ⪚ +<quote>Use the left mouse button to select and copy text, and the +middle mouse button to paste it.</quote></para> +</listitem> +<listitem> +<para>Keep to logical sentence order.</para> +<para>For example, <quote>&konqueror; is a web browser with the +ability to browse file systems and it includes a javascript +interpreter.</quote> (Do you see why this is awkward?)</para> +</listitem> +<listitem> +<para>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.</para> +</listitem> +<listitem> +<para>Do not start sentences with any of <quote>and,</quote> +<quote>so,</quote> <quote>but,</quote> <quote>because,</quote> or +<quote>however.</quote></para> +</listitem> +<listitem> +<para>Try to avoid contractions, rather spell out both words; ⪚, +<quote>it is</quote> rather than <quote>it's</quote>; <quote>can +not</quote> rather than <quote>can't</quote></para> +</listitem> +<listitem> +<para>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 <acronym>XSLT</acronym> +stylesheets in use.</para> +</listitem> +</itemizedlist> + +<para>Remember, we have also an active proofreading team, and there is +always someone to help you with grammar, so just +write and have fun!</para> + +</chapter> + +<chapter id="resources"> +<title>Resources</title> + +<sect1 id="general-purpose-sites"> +<title>General Purpose Websites</title> + +<para>A few sites you may find worth bookmarking, or at least +visiting.</para> + +<sect2 id="dictionary-sites"> +<title>Dictionary Sites</title> + +<itemizedlist> +<listitem> +<para><ulink url="http://www.m-w.com/">Merriam Webster +Online</ulink></para> +</listitem> +<listitem> +<para><ulink +url="http://www.dictionary.com/">Dictionary.com</ulink></para> +</listitem> +</itemizedlist> + +</sect2> + +<sect2 id="thesaurus-sites"> +<title>Thesaurus Sites</title> + +<itemizedlist> +<listitem> +<para><ulink url="http://www.m-w.com/">Merriam-Webster</ulink> have a +thesaurus as well as a dictionary</para> +</listitem> +<listitem> +<para><ulink url="http://www.thesaurus.com/">Roget's +Thesaurus</ulink></para> +</listitem> +</itemizedlist> + +</sect2> + +<sect2 id="other-style-guides"> +<title>Style Guides and Other Resources</title> + +<itemizedlist> +<listitem> +<para><ulink +url="http://www.cc.columbia.edu/acis/bartleby/strunk/">Strunk & +White</ulink> 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.</para> </listitem> + +<listitem> +<para>The <ulink +url="news://alt.usage.english">alt.usage.english</ulink> newsgroup. +If you'd like every sentence chewed over, dissected, and then +rewritten several conflicting ways, or some great advice about bacon, +you'll 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 <acronym>FAQ</acronym>'s before asking a question.</para> +</listitem> +</itemizedlist> +<para>Other possibly useful sites</para> + +<itemizedlist> +<listitem><para><ulink +url="http://hotwired.lycos.com/hardwired/wiredstyle/biblio/">The Wired + Style Guide Bookmarks section</ulink></para> +</listitem> + +<listitem> +<para><ulink +url="http://www2.rscc.cc.tn.us/%7Ejordan_jj/OWL/Clutter.html">http://www2.rscc.cc.tn.us/~jordan_jj/OWL/Clutter.html</ulink> +If you tend to write very wordy sentences, here's a page with some +help for you. Includes a useful table of ways to rewrite common +mistakes.</para> +</listitem> +<listitem> +<para><ulink +url="http://owl.english.purdue.edu/Files/116.html">http://owl.english.purdue.edu/Files/116.html +</ulink> is a page about how to make sentences <quote>flow</quote> +better</para> +</listitem> +</itemizedlist> +</sect2> +</sect1> + +</chapter> + +<!-- &trademarks; --> + + +<chapter id="credits-and-license"> +<title>Credits and Licenses</title> + +<para>The &tde; Documentation Style Guide</para> + +<!-- FIXME proper credits section --> +<para>Copyright 2002, Lauri Watts, Mike McBride, Eric Bischoff, +Frederik Fouvry.</para> +<para>Copyright &tde-copyright-date;, &tde-authors;.</para> + +&underFDL; + +</chapter> + +<!-- &wordlist; --> + +</book> |