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
|
<chapter id="improving">
<title>Ways to Improve Your Documentation</title>
<para> This chapter provides you with tips that can help you to improve the
readability and effectiveness of the documentation that you write. This chapter
does not describe how to troubleshoot the XML code in your document. </para>
<sect1 id="improving-1">
<title>Reviews</title>
<para> Good reviews are the secret of good documentation. This section
tells you about the different types of review that you can use during the
development of documentation. In the ideal project, every item of documentation
goes through each of the following reviews in the given order, and each review type is completed before the next review type is started. </para>
<sect2 id="improving-2">
<title>Technical Review</title>
<para> The developer is your main source of information for the products
that you write about. Use the developer as a source of expert knowledge to do
the following reviews:
<itemizedlist>
<listitem>
<para> Initial review of the first draft for technical accuracy and to ensure that all functionality is documented.
</para>
</listitem>
<listitem>
<para> Final technical verification review after you have
implemented all comments from other reviewers. </para>
</listitem>
</itemizedlist> </para>
</sect2>
<sect2 id="improving-3">
<title>Peer Review</title>
<para> Make an agreement with a colleague writer to review your work. The
ideal conditions for a peer review are as follows:
<itemizedlist>
<listitem>
<para> The reviewer is not familiar with the product before the
review. </para>
</listitem>
<listitem>
<para> The reviewer reviews your documentation against the product
functionality to ensure that all descriptions and instructions are correct. </para>
</listitem>
</itemizedlist> </para>
</sect2>
<sect2 id="improving-4">
<title>Editorial Review</title>
<para> An editorial review is essential. You should make a formal
arrangement for an editor to review your work. Allow plenty of time for an editorial
review, in advance of the date you plan to submit the documentation. </para>
<para> The editor checks the documentation against the agreed standards
that you use to write the documentation. The editor ensures that you have
followed general structural rules, for topics such as capitalization, spelling,
punctuation, and grammar. The editor also ensures that the documentation
adheres to specific rules such as terminology defined in
<xref linkend="wordlist"/>. </para>
</sect2>
<sect2 id="improving-5">
<title>User Review</title>
<para> Ask someone who is not familiar with the product to try out the
product. Set a series of tasks for the user to complete. Instruct the user to
refer to the documentation during the execution of the tasks. This type of
review answers the following questions about the documentation:
<itemizedlist>
<listitem>
<para> How easily can users find relevant information? </para>
</listitem>
<listitem>
<para> How easily can users transfer information to the product?
</para>
</listitem>
<listitem>
<para> What user information is missing? </para>
</listitem>
</itemizedlist> If you need help setting up a user review, ask the
GNOME usability team, or another author who has done such a review. </para>
<note>
<para>Practicalities make a user review a rare treat, rather than an expected part of the documentation process.
</para>
</note>
</sect2>
<sect2 id="improving-5b">
<title>Publication Review</title>
<para>Ask a colleague to have a quick glance through the document to ensure publication readiness.
</para>
</sect2>
</sect1>
<sect1 id="improving-6">
<title>Checks You Can Do Yourself</title>
<para> You can do a variety of checks on your writing during the
development of your documentation, in the following areas. </para>
<sect2 id="top-level-checks">
<title>Top-Level Checks</title>
<para> You can perform the following top-level checks regularly during
documentation development: </para>
<itemizedlist>
<listitem>
<para> Wordcount </para>
<para> As soon as a sentence or a procedure step starts to look
suspiciously long, do a wordcount. See <xref linkend="fundamentals-2"/>,
<emphasis>Golden Rule 1</emphasis>. </para>
</listitem>
<listitem>
<para> Spellcheck </para>
<para> Run regular spellchecks. Make sure that agreed terms from
<xref linkend="wordlist"/> are in your spellchecker dictionary. </para>
</listitem>
<listitem>
<para> Pronouns search </para>
<para> Search for the following pronouns: </para>
<itemizedlist>
<listitem>
<para> It </para>
</listitem>
<listitem>
<para> They </para>
</listitem>
<listitem>
<para> Them </para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para> If you find any of the above pronouns, rewrite the sentences to
eliminate the pronoun. </para>
</sect2>
<sect2 id="top-ten-topics">
<title>Top Ten Topics to Watch Out For</title>
<para> The following table lists the top ten topics that you need to
watch out for when you review your work, or when you perform a peer review for
a colleague. Review the documentation against the typical problem areas listed
in the table. The problem areas in the table are not exhaustive, you may
encounter more pitfalls during your review. The table provides you with cues so
that you can review your work with these topics and problem areas in mind. You
can find advice about how to deal with these topics in other sections of this
style guide. </para>
<informaltable frame="topbot">
<tgroup cols="2" align="left">
<colspec colname="col1" colwidth="0.32*" align="left"/>
<colspec colname="col2" colwidth="1.68*" align="left"/>
<thead>
<row valign="top" rowsep="1">
<entry colname="col1" colsep="0" valign="top" align="left">
<para> Topic </para> </entry>
<entry colname="col2" colsep="0" valign="top" align="left">
<para> Typical Problem Areas </para> </entry>
</row>
</thead>
<tbody>
<row valign="top">
<entry colname="col1" colsep="0" rowsep="0" align="left"
valign="top">
<para> Accuracy </para> </entry>
<entry colname="col2" colsep="0" rowsep="0" align="left"
valign="top">
<para>
<itemizedlist>
<listitem>
<para> Functions differ from the description. </para>
</listitem>
<listitem>
<para> Functions are not described </para>
</listitem>
<listitem>
<para> Functions are referred to using different
terminology from the user interface. </para>
</listitem>
<listitem>
<para> Functions are described that do not exist. </para>
</listitem>
<listitem>
<para> The description provides irrelevant and possibly
confusing information. </para>
</listitem>
</itemizedlist> </para> </entry>
</row>
<row valign="top">
<entry colname="col1" colsep="0" rowsep="0" align="left"
valign="top">
<para> Clarity </para> </entry>
<entry colname="col2" colsep="0" rowsep="0" align="left"
valign="top">
<para>
<itemizedlist>
<listitem>
<para> Ambiguous statements </para>
</listitem>
<listitem>
<para> Inconsistency </para>
</listitem>
<listitem>
<para> Unexplained events </para>
</listitem>
<listitem>
<para> Undefined terms </para>
</listitem>
<listitem>
<para> Vague, defensive language </para>
</listitem>
</itemizedlist> </para> </entry>
</row>
<row valign="top">
<entry colname="col1" colsep="0" rowsep="0" align="left"
valign="top">Editorial</entry>
<entry colname="col2" colsep="0" rowsep="0" align="left"
valign="top">
<para>
<itemizedlist>
<listitem>
<para> Repeated words </para>
</listitem>
<listitem>
<para> Misspelled words </para>
</listitem>
<listitem>
<para> Typographical errors </para>
</listitem>
<listitem>
<para> Missing words </para>
</listitem>
<listitem>
<para> Verbs in the wrong tense </para>
</listitem>
</itemizedlist> </para> </entry>
</row>
<row valign="top">
<entry colname="col1" colsep="0" rowsep="0" align="left"
valign="top">
<para> Grammar and Syntax </para> </entry>
<entry colname="col2" colsep="0" rowsep="0" align="left"
valign="top">
<para>
<itemizedlist>
<listitem>
<para> Tenses other than the present tense </para>
</listitem>
<listitem>
<para> Long sentences joined by conjunctions, such as
<emphasis> and</emphasis>. </para>
</listitem>
<listitem>
<para> Long sentences with confusing subordinate clauses
</para>
</listitem>
<listitem>
<para> Incomplete sentences that leave out the articles
</para>
</listitem>
<listitem>
<para> Over-elaborate sentence structure and syntax.
</para>
</listitem>
</itemizedlist> </para> </entry>
</row>
<row valign="top">
<entry colname="col1" colsep="0" rowsep="0" align="left"
valign="top">
<para> Graphics </para> </entry>
<entry colname="col2" colsep="0" rowsep="0" align="left"
valign="top">
<para>
<itemizedlist>
<listitem>
<para> Wrong graphic referred to in text. </para>
</listitem>
<listitem>
<para> Graphic has different features from the
description. </para>
</listitem>
<listitem>
<para> Unnecessary use of formal figures. </para>
</listitem>
<listitem>
<para> Incorrect use of informal figures. </para>
</listitem>
<listitem>
<para> Graphics do not adhere to graphics style rules.
</para>
</listitem>
</itemizedlist> </para> </entry>
</row>
<row valign="top">
<entry colname="col1" colsep="0" rowsep="0" align="left"
valign="top">
<para> Information Design </para> </entry>
<entry colname="col2" colsep="0" rowsep="0" align="left"
valign="top">
<para>
<itemizedlist>
<listitem>
<para> Series of points are described in prose rather
than an itemized list. </para>
</listitem>
<listitem>
<para> Sequences of actions are described in prose rather
than a numbered list. </para>
</listitem>
<listitem>
<para> Topics are described in sequential paragraphs
rather than in tables. </para>
</listitem>
<listitem>
<para> Information is ordered incorrectly within a
document. </para>
</listitem>
<listitem>
<para> Unclear or insufficient examples to support the
descriptions. </para>
</listitem>
</itemizedlist> </para> </entry>
</row>
<row valign="top">
<entry colname="col1" colsep="0" rowsep="0" align="left"
valign="top">
<para> Legal </para> </entry>
<entry colname="col2" colsep="0" rowsep="0" align="left"
valign="top">
<para>
<itemizedlist>
<listitem>
<para> Unsubstantiated claims </para>
</listitem>
<listitem>
<para> Incorrect description of functions </para>
</listitem>
<listitem>
<para> Insufficient notice of potential damage or hazard
</para>
</listitem>
<listitem>
<para> Statements about future features </para>
</listitem>
<listitem>
<para> Statements about competing products </para>
</listitem>
</itemizedlist> </para> </entry>
</row>
<row valign="top">
<entry colname="col1" colsep="0" rowsep="0" align="left"
valign="top">
<para> Punctuation </para> </entry>
<entry colname="col2" colsep="0" rowsep="0" align="left"
valign="top">
<para>
<itemizedlist>
<listitem>
<para> Use of slash, and
<emphasis>and/or</emphasis></para>
</listitem>
<listitem>
<para> Inconsistent use of hyphens and dashes</para>
</listitem>
<listitem>
<para> Inappropriate use of parentheses and
brackets</para>
</listitem>
<listitem>
<para> Incorrect use of apostrophes</para>
</listitem>
<listitem>
<para> Incorrect use of quotation marks</para>
</listitem>
</itemizedlist> </para> </entry>
</row>
<row valign="top">
<entry colname="col1" colsep="0" rowsep="0" align="left"
valign="top">
<para> Style and Usage </para> </entry>
<entry colname="col2" colsep="0" rowsep="0" align="left"
valign="top">
<para>
<itemizedlist>
<listitem>
<para> Inconsistent capitalization </para>
</listitem>
<listitem>
<para> Failure to use the terms in
<xref linkend="wordlist"/> </para>
</listitem>
<listitem>
<para> Use of terminology outside the
<ulink url="http://www.bartleby.com/61/">
<citetitle>American Heritage
Dictionary</citetitle></ulink> </para>
</listitem>
<listitem>
<para> Inconsistent use of terminology </para>
</listitem>
<listitem>
<para> Wordy explanations </para>
</listitem>
</itemizedlist> </para> </entry>
</row>
<row valign="top">
<entry colname="col1" colsep="0" rowsep="0" align="left"
valign="top">
<para> Tone </para> </entry>
<entry colname="col2" colsep="0" rowsep="0" align="left"
valign="top">
<para>
<itemizedlist>
<listitem>
<para> Jargon </para>
</listitem>
<listitem>
<para> Colloquial language </para>
</listitem>
<listitem>
<para> Humor </para>
</listitem>
<listitem>
<para> Culture-specific references </para>
</listitem>
<listitem>
<para> Gender-specific language </para>
</listitem>
<listitem>
<para> Condescension </para>
</listitem>
</itemizedlist> </para> </entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect2>
</sect1>
</chapter>
|
