1
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Basics of Documentation Style</title><meta name="generator" content="DocBook XSL Stylesheets V1.56.1"><link rel="home" href="index.html" title="The GNOME Handbook of Writing Software Documentation"><link rel="up" href="index.html" title="The GNOME Handbook of Writing Software Documentation"><link rel="previous" href="ar01s11.html" title="Referring to Other GNOME Documentation (coming in
2
GNOME-2.0)"><link rel="next" href="ar01s13.html" title="Teamwork"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Basics of Documentation Style</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s11.html">Prev</a>�</td><th width="60%" align="center">�</th><td width="20%" align="right">�<a accesskey="n" href="ar01s13.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="basics"></a>Basics of Documentation Style</h2></div></div><p>
3
Most people have never enjoyed reading a software manual, and
4
they probably never will. Many times, they'll read the
5
documentation only when they run into problems, and they'll be
6
frustrated and upset before they even read a word. On the
7
other hand, some readers will read the manual all the way
8
through, or at least look at the introduction before they
9
start. Your document might serve as a reference for an expert
10
or a guide to a beginner, and it must have enough depth to
11
satisfy the first without overwhelming the second. Ideally, it
12
will serve beginners as they <span class="emphasis"><em>become</em></span>
13
experts. Remember, your goal is to produce <span class="emphasis"><em>complete,
14
intuitive and clear</em></span> documentation.
16
In order to write useful documentation, you'll have to know who
17
your audience is likely to be. Then, you can look for the
18
problems they're likely to run into, and solve them. It will
19
also help if you focus on the tasks users will perform, and
20
group features accordingly, rather than simply describing
22
</p><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="styleplanning"></a>Planning</h3></div></div><p>
23
Begin documenting by learning how to use the application and
24
reading over any existing documentation. Pay attention to
25
places where your document will differ from the template. It
26
may help to develop a document skeleton: a valid XML or SGML
27
document that has little or no content. For very large
28
applications, you will need to make significant departures
29
from the templates, since you'll be using the
30
<tt class="sgmltag-element"><book></tt> tag instead of
31
<tt class="sgmltag-element"><chapter></tt> or
32
<tt class="sgmltag-element"><article></tt>.
33
</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="balance"></a>Achieving a Balanced Style</h3></div></div><p>
34
Just as you need to juggle expert and novice readers,
35
you'll have to juggle a number of other extremes as you write:
36
</p><div class="itemizedlist"><ul type="disc"><li><p>
37
Documents should be complete, yet concise. You should
38
describe every feature, but you'll have decide how much
39
detail is really necessary. It's not, for example,
40
necessary to describe every button and form field in a
41
dialog box, but you should make sure that your readers
42
know how to bring up the dialog and what it does. If
43
you spend fewer words on the obvious, you can spend more
44
time clarifying the ambiguous labels and explaining
45
items that are more complex.
47
Be engaging and friendly, yet professional. Games
48
documents may be less formal than productivity
49
application documents (people don't
50
<span class="emphasis"><em>use</em></span> games, they
51
<span class="emphasis"><em>play</em></span> them), but all of them should
52
maintain a standard of style which holds the reader's
53
interest without resorting to jokes and untranslatable
56
Examples, tips, notes, and screenshots are useful to
57
break up long stretches of text, but too many can get in
58
the way, and make your documents too choppy to read.
59
It's good to provide a screenshot of any dialog windows
60
a user might run into, but if a dialog box has several
61
tabs, it's not usually necessary to have one for each.
63
The GDP strives to have all of its documentation conform
64
to certain standards of style and content, but every
65
document (and every writer) is different. You will need
66
to use your judgement, and write documents to fit with
67
the rest of the project, without compromising the
68
individual needs of your subject, or your own
69
individuality as a writer.
70
</p></li></ul></div><p>
71
</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="stylestructure"></a>Structure</h3></div></div><p>
72
In general, you won't have to worry too much about structure,
73
because the templates provide you with an excellent example.
74
As a general rule, try to follow that structural example.
75
That means using links, hierarchical nesting, and, if
76
necessary, a glossary or index. You probably won't need to
77
use every available structural tag, but take advantage of
78
what DocBook provides you.
80
As to linking, there's some disagreement about whether to use
81
<tt class="sgmltag-element"><xref></tt> <tt class="sgmltag-element"><link></tt>
82
when you make links within your documents. You'll have to
83
decide, based on the different ways that they are presented
84
in output, which is more appropriate given the context.
85
Regardless of which you use, you should not forget to use
86
them. Help your readers find information that relevant to
89
The table of contents will be generated automatically, but
90
you will probably have to develop your own index if you wish
91
to have one. The Nautilus Help Browser will have new, and
92
currently unknown, indexing capabilities, so index style and
93
structure are still under discussion. The GNOME User's Guide
94
will contain a glossary in its next versions; unless you're
95
writing a<tt class="sgmltag-element"><book></tt>, it will probably be best to
96
contribute to that rather than developing your own.
97
</p></div><div class="sect2"><div class="titlepage"><div><h3 class="title"><a name="stylegrammar"></a>Grammar and Spelling</h3></div></div><p>
98
Nobody expects you to be perfect; they just expect the
99
documentation for their software to be error-free. That means
100
that, in the same way that developers look for bugs and accept
101
bug reports, writers must check for errors in their documents.
102
Poor grammar, bad spelling, and gross technical errors in
103
draft documents are fine. However, if those problems show up
104
in a "real" release, they can count against the credibility of
105
GNOME and Linux. They'll also make you look bad.
107
There is no substitute for a human proofreader; use a
108
spell-check program, then read it over yourself, and then find
109
someone else to help you. Other GDP members are, of course,
110
willing and able to help you, but non-writers are often at
113
Proofreading documents is both a also a good way to
114
familiarize yourself with documentation, and it certainly
115
makes you valuable to the GDP. Help other writers proof their
116
documents, and they will help you with yours.
117
</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s11.html">Prev</a>�</td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right">�<a accesskey="n" href="ar01s13.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Referring to Other GNOME Documentation (coming in
118
GNOME-2.0)�</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">�Teamwork</td></tr></table></div></body></html>
added
removed
tests/docbook/result/xtchunk/html/ar01s12.orig
