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
|
<chapter id="fundamentals">
<title>Fundamental Concepts of Technical Documentation</title>
<para> This chapter provides a brief introduction to writing technical
documentation. </para>
<sect1 id="fundamentals-1">
<title>General Style Requirements</title>
<para> Technical writing for computer applications imposes special
constraints beyond the basic requirements of good prose. Good technical
documentation has the following characteristics: </para>
<variablelist>
<varlistentry>
<term> Comprehensive</term>
<listitem>
<para> Describe all of the functionality of a product. Do not omit
functionality that you regard as irrelevant for the user. </para>
</listitem>
</varlistentry>
<varlistentry>
<term> Conformant</term>
<listitem>
<para> Describe what you see. Do not describe what you want to see.
Present your information in the order that users experience the subject matter.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term> Clear</term>
<listitem>
<para> Read
<ulink url="http://www.bartleby.com/141/">
<citetitle>The Elements of Style</citetitle></ulink> to help make
your writing clear. </para>
</listitem>
</varlistentry>
<varlistentry>
<term> Consistent</term>
<listitem>
<para> Use agreed vocabulary throughout your documentation. Use the
same vocabulary as other writers who are working on related documentation.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Concise</term>
<listitem>
<para> Review your work frequently as you write your document. Ask
yourself which words you can take out. See <xref linkend="fundamentals-2"/> for
a specific guideline. </para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="fundamentals-2">
<title>Golden Rules</title>
<para> This section contains some basic style guidelines. Subsequent
chapters of this book expand on these guidelines to give more detailed
guidance. </para>
<para>
<informaltable frame="topbot">
<tgroup cols="2" colsep="0" rowsep="0"><colspec colnum="1"
colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2"
colwidth="511.50pt"/>
<tbody>
<row>
<entry colname="col1" valign="top" align="left">
<para> Golden Rule 1 </para> </entry>
<entry colname="col2" valign="top" align="left">
<para>
<itemizedlist>
<listitem>
<para> Limit each sentence to less than 25 words. </para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para> Limit each procedure step to 23 words. </para>
</listitem>
</itemizedlist> </para> </entry>
</row>
<row>
<entry colname="col1" valign="top" align="left">
<para> Example </para> </entry>
<entry colname="col2" valign="top" align="left">
<para> Under normal operating conditions, the kernel does not
always immediately write file data to the disks, storing it in a memory buffer
and then periodically writing to the disks to speed up operations. </para>
</entry>
</row>
<row>
<entry colname="col1" valign="top" align="left">
<para> Rewrite </para> </entry>
<entry colname="col2" valign="top" align="left">
<para> Normally, the kernel stores the data in memory prior to
periodically writing the data to the disk. </para> </entry>
</row>
</tbody>
</tgroup>
</informaltable> </para>
<para>
<informaltable frame="topbot">
<tgroup cols="2" colsep="0" rowsep="0"><colspec colnum="1"
colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2"
colwidth="512.25pt"/>
<tbody>
<row>
<entry colname="col1" valign="top" align="left">
<para> Golden Rule 2 </para> </entry>
<entry colname="col2" valign="top" align="left">
<para>
<itemizedlist>
<listitem>
<para> Limit each paragraph to one topic. </para>
</listitem>
<listitem>
<para> Limit each sentence to one idea. </para>
</listitem>
<listitem>
<para> Limit each procedure step to one action. </para>
</listitem>
</itemizedlist> </para> </entry>
</row>
<row>
<entry colname="col1" valign="top" align="left">
<para> Example </para> </entry>
<entry colname="col2" valign="top" align="left">
<para> The <application>Workspace Switcher</application> applet
helps you navigate all of the virtual desktops available on your system. The X
Window system, working in hand with a piece of software called a
<emphasis>window manager</emphasis>, allows you to create more than one virtual
desktop, known as <emphasis>workspaces</emphasis>, to organize your work, with
different applications running in each workspace. The <application>Workspace
Switcher</application> applet is a navigational tool to get around the various
workspaces, providing a miniature road map in the GNOME panel showing all your
workspaces and allowing you to switch easily between them. </para> </entry>
</row>
<row>
<entry colname="col1" valign="top" align="left">
<para> Rewrite </para> </entry>
<entry colname="col2" valign="top" align="left">
<para> You can use the <application>Workspace
Switcher</application> to add new <emphasis>workspaces</emphasis> to the GNOME
Desktop. You can run different applications in each workspace. The
<application>Workspace Switcher</application> applet provides a miniature map
that shows all of your workspaces. You can use the <application>Workspace
Switcher</application> applet to switch between workspaces. </para> </entry>
</row>
<row>
<entry colname="col1" valign="top" align="left">
<para> Tip </para> </entry>
<entry colname="col2" valign="top" align="left">
<para> Plan the order of paragraphs before you start writing.
Decide which topic you want to cover in each paragraph. </para> </entry>
</row>
</tbody>
</tgroup>
</informaltable> </para>
<para>
<informaltable frame="topbot">
<tgroup cols="2" colsep="0" rowsep="0"><colspec colnum="1"
colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2"
colwidth="512.25pt"/>
<tbody>
<row>
<entry colname="col1" valign="top" align="left">
<para> Golden Rule 3 </para> </entry>
<entry colname="col2" valign="top" align="left">
<para> Use explicit examples to demonstrate how an application
works. Provide instructions rather than descriptions. </para> </entry>
</row>
<row>
<entry colname="col1" valign="top" align="left">
<para> Example </para> </entry>
<entry colname="col2" valign="top" align="left">
<para> There is a text box that you can use to find out the
definition of a word. </para> </entry>
</row>
<row>
<entry colname="col1" valign="top" align="left">
<para> Rewrite </para> </entry>
<entry colname="col2" valign="top" align="left">
<para> To request a definition of a word, type the word in the
text box, then click on the Lookup button. </para> </entry>
</row>
<row>
<entry colname="col1" valign="top" align="left">
<para> Tip </para> </entry>
<entry colname="col2" valign="top" align="left">
<para> Do not apply this guideline too rigidly. Sometimes you
must explain how software works to support your how-to examples. </para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable> </para>
<para>
<informaltable frame="topbot">
<tgroup cols="2" colsep="0" rowsep="0"><colspec colnum="1"
colname="col1" colwidth="1.00*"/><colspec colnum="2" colname="col2"
colwidth="514.50pt"/>
<tbody>
<row>
<entry colname="col1" valign="top" align="left">
<para> Golden Rule 4 </para> </entry>
<entry colname="col2" valign="top" align="left">
<para> Write in a neutral tone. </para> </entry>
</row>
<row>
<entry colname="col1" valign="top" align="left">
<para> Example </para> </entry>
<entry colname="col2" valign="top" align="left">
<para> The applet is a handy little screen grabber. </para>
</entry>
</row>
<row>
<entry colname="col1" valign="top" align="left">
<para> Rewrite </para> </entry>
<entry colname="col2" valign="top" align="left">
<para> You use the applet to take screenshots. </para> </entry>
</row>
</tbody>
</tgroup>
</informaltable> </para>
</sect1>
<sect1 id="fundamentals-3">
<title>Tone</title>
<para> Inappropriate tone can hinder reader access to information. A
neutral tone free of opinion or personal flavor reduces the processing load for
the reader to understand the information. Another benefit of a neutral tone is
that several writers can work in parallel on a large technical documentation
project. Furthermore, different writers can join the project at different
times. The use of a neutral tone helps to achieve consistency across a
documentation set, and thereby facilitates user access to information. The best
way to achieve a common, neutral tone is to apply the following principles:
<variablelist>
<varlistentry>
<term>Avoid humor</term>
<listitem>
<para> Humor distracts from the information you are trying to
provide. Humor also makes documentation difficult to translate. Stay factual.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Avoid personal opinions</term>
<listitem>
<para> Whether you think a function is useful or woeful is
irrelevant. Report the function to the user, with instructions about how to use
the function. Stay accurate. </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Avoid colloquial language</term>
<listitem>
<para> Colloquial language is difficult to translate and usually
culture-specific. Stay neutral. </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Avoid topical expressions</term>
<listitem>
<para> An expression that is in common use today might convey
something completely different tomorrow. Stay technical. </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Avoid aspirational statements</term>
<listitem>
<para> Statements about the future developments of a product do not
belong in technical documentation. Write about what you see right now. Stay
real. </para>
</listitem>
</varlistentry>
</variablelist> </para>
</sect1>
<sect1 id="fundamentals-4">
<title>Reaching the Right Audience</title>
<para> All of the decisions that you make about the structure and content
of a manual follow from an understanding of the audience. You need to think
about how the audience accesses the documentation, what sort of information the
audience needs, and the experience level of the audience. Usually, you need to
create documentation that is suitable for different audiences. The following
sections introduce some of the audience-related topics you need to consider.
</para>
<sect2 id="fundamentals-6">
<title>User Motivation</title>
<para> Do not waste the time of the user who looks for information in
your documentation. Users do not read technical documentation for
entertainment. Users usually have specific questions. You need to give clear
answers to those questions. </para>
</sect2>
<sect2 id="fundamentals-7">
<title>New Users</title>
<para> New users to the GNOME Desktop are likely to consult online Help
for guidance about unfamiliar applications or functionality. Each Help manual
should contain enough introductory information to tell new users how to start
using the application. Each Help manual should also contain enough usage
instructions to tell users the different actions that they can perform with the
application. Keep these instructions task-oriented. You do not need to describe
GUI screens, dialogs, and dialog elements in Help, unless there is an unusual
feature that affects your instructions. </para>
</sect2>
<sect2 id="fundamentals-8">
<title>Experienced Users</title>
<para> Experienced users are more likely to use documentation as a
reference. The documentation therefore needs to be complete, well-organized,
and in the case of printed manuals, well-indexed. </para>
</sect2>
<sect2 id="fundamentals-9">
<title>Do Not Offend Your Audience</title>
<para> To avoid offending your readers, apply the following guidelines to
your documentation:
<variablelist>
<varlistentry>
<term>Avoid insider language</term>
<listitem>
<para> Insider language includes both undefined jargon and the
tendency of the computer community to shorten words. For example, use the term
<emphasis>documentation</emphasis> instead of the term
<emphasis>docs</emphasis>. You can identify jargon if terminology fails the
following conditions:
<itemizedlist>
<listitem>
<para> A term does not appear in <xref
linkend="wordlist"/>, in this guide. </para>
</listitem>
<listitem>
<para> A term does not appear in the
<ulink url="http://www.bartleby.com/61/">
<citetitle>American Heritage
Dictionary</citetitle></ulink>. </para>
</listitem>
<listitem>
<para> A term does not appear in the glossary of the manual
that you are writing. </para>
</listitem>
<listitem>
<para> A term is not defined in the body text of the manual
that you are writing. </para>
</listitem>
</itemizedlist> </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Avoid sexist language</term>
<listitem>
<para> Pronoun constructions such as <emphasis>his/her</emphasis>
or <emphasis>s/he</emphasis> do not exist. There is no need to identify gender
in your instructions. </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Avoid culture-specific language</term>
<listitem>
<para> There is little point in giving an example that everyone
in your town knows about, but is a complete mystery to everyone else in the
world. </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Avoid talking down to your reader</term>
<listitem>
<para> There are few experiences more irritating for a user than
documentation that says an action is easy or quick, when in fact the user
cannot complete the action. Do not qualify or prejudge actions. </para>
</listitem>
</varlistentry>
</variablelist> </para>
<para> Other parts of this guide discuss in more detail tone and language
usage that can cause offense. </para>
</sect2>
</sect1>
<sect1 id="fundamentals-5">
<title>Structure</title>
<para> Good organization goes a long way towards creating good
documentation. You need to consider the type of manual that you want to create
before you start work. Not every manual can follow the same structure. You must
break up a complex, multifunction application such as
<application>Evolution</application> into many parts, to provide detailed
explanations of the separate functional modules. An applet, on the other hand,
needs a brief description of the GUI, basic usage instructions, and details on
any necessary preferences. </para>
<sect2 id="fundamentals-10">
<title>Help Manuals</title>
<para> Wherever possible, use templates to ensure that your Help manual
follows a standard approach. You can find templates for Help manuals in the
<ulink
url="http://developer.gnome.org/projects/gdp/handbook/gdp-handbook/">
<citetitle>GNOME Handbook of Writing Software
Documentation</citetitle></ulink>.</para>
</sect2>
<sect2 id="fundamentals-11">
<title>Guides</title>
<para> If you need to write a guide about a large application or a set of
applications, then the book is substantially longer than a Help manual. You
need to develop an outline plan for your guide. The precise composition of your
manual depends on the subject, however in general you need the following book
components: </para>
<variablelist>
<varlistentry>
<term>Front matter</term>
<listitem>
<para> Defines the function of the book. Includes navigation aids
to the remaining sections of the book, such as a table of contents, or links.
This section might contain a Preface. </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Introduction</term>
<listitem>
<para> Explains the application to new users. You should provide an
expanded definition of the function of the application, built around
illustrations and examples. </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Document body</term>
<listitem>
<para> Consists of several sections or chapters that provide a more
detailed explanation of how to use the application. This is where you achieve
completeness, telling the user how to complete all the main tasks associated
with the application. Chapter headings are usually descriptive of the each
topic area. Sub-headings within the chapter are usually task-oriented, so that
users can quickly find information about a specific action within the topic
area. </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Glossary</term>
<listitem>
<para> Defines specific terms in the book. You do not need to
define terms that are in the
<ulink url="http://www.bartleby.com/61/">
<citetitle>American Heritage
Dictionary</citetitle></ulink>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Appendices</term>
<listitem>
<para> Contain additional notes about related topics that are not
directly explained in the document body. </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Index</term>
<listitem>
<para> Provides keyword links to specific concepts in the book.
Follow the guidelines in this guide to create an effective index. </para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>
</chapter>
|
