summaryrefslogtreecommitdiffstats
path: root/doc/tutorials/styleguide/index.docbook
blob: 8c943562f9ae9634ce59e2f98703e333c97ff93d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
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>trinity-devel@lists.pearsoncomputing.net</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, &eg; <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 &mdash; 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, &eg;
<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; &eg;,
<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 &amp;
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>