You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
467 lines
15 KiB
467 lines
15 KiB
<?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>devels@trinitydesktop.org</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 kde-doc-english@kde.org 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>
|