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
|
<!--startcut ==============================================-->
<!-- *** BEGIN HTML header *** -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML><HEAD>
<title>A Need for Documentation LG #71</title>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#0000AF"
ALINK="#FF0000">
<!-- *** END HTML header *** -->
<CENTER>
<A HREF="http://www.linuxgazette.com/">
<IMG ALT="LINUX GAZETTE" SRC="../gx/lglogo.png"
WIDTH="600" HEIGHT="124" border="0"></A>
<BR>
<!-- *** BEGIN navbar *** -->
<IMG ALT="" SRC="../gx/navbar/left.jpg" WIDTH="14" HEIGHT="45" BORDER="0" ALIGN="bottom"><A HREF="lg_tips71.html"><IMG ALT="[ Prev ]" SRC="../gx/navbar/prev.jpg" WIDTH="16" HEIGHT="45" BORDER="0" ALIGN="bottom"></A><A HREF="lg_toc71.html"><IMG ALT="[ Table of Contents ]" SRC="../gx/navbar/toc.jpg" WIDTH="220" HEIGHT="45" BORDER="0" ALIGN="bottom" ></A><A HREF="../lg_frontpage.html"><IMG ALT="[ Front Page ]" SRC="../gx/navbar/frontpage.jpg" WIDTH="137" HEIGHT="45" BORDER="0" ALIGN="bottom"></A><A HREF="http://www.linuxgazette.com/cgi-bin/talkback/all.py?site=LG&article=http://www.linuxgazette.com/issue71/arndt.html"><IMG ALT="[ Talkback ]" SRC="../gx/navbar/talkback.jpg" WIDTH="121" HEIGHT="45" BORDER="0" ALIGN="bottom" ></A><A HREF="../lg_faq.html"><IMG ALT="[ FAQ ]" SRC="./../gx/navbar/faq.jpg"WIDTH="62" HEIGHT="45" BORDER="0" ALIGN="bottom"></A><A HREF="joshi.html"><IMG ALT="[ Next ]" SRC="../gx/navbar/next.jpg" WIDTH="15" HEIGHT="45" BORDER="0" ALIGN="bottom" ></A><IMG ALT="" SRC="../gx/navbar/right.jpg" WIDTH="15" HEIGHT="45" ALIGN="bottom">
<!-- *** END navbar *** -->
<P>
</CENTER>
<!--endcut ============================================================-->
<H4 ALIGN="center">
"Linux Gazette...<I>making Linux just a little more fun!</I>"
</H4>
<P> <HR> <P>
<!--===================================================================-->
<center>
<H1><font color="maroon">A Need for Documentation</font></H1>
<H4>By <a href="mailto:matthiasarndt@gmx.net">Matthias Arndt</a></H4>
</center>
<P> <HR> <P>
<!-- END header -->
<H2><A NAME="SECTION00010000000000000000">
Contents</A>
</H2>
<!--Table of Contents-->
<UL>
<LI><A NAME="tex2html15"
HREF="#SECTION00020000000000000000">1 Introduction</A>
<LI><A NAME="tex2html16"
HREF="#SECTION00030000000000000000">2 Why should I write documentation?</A>
<LI><A NAME="tex2html17"
HREF="#SECTION00040000000000000000">3 What aspects of my project/program should I document?</A>
<LI><A NAME="tex2html18"
HREF="#SECTION00050000000000000000">4 How do I write documentation?</A>
<LI><A NAME="tex2html19"
HREF="#SECTION00060000000000000000">5 What formats should I use for my documentation?</A>
<UL>
<LI><A NAME="tex2html20"
HREF="#SECTION00061000000000000000">5.1 File formats suitable for documentation</A>
<LI><A NAME="tex2html21"
HREF="#SECTION00062000000000000000">5.2 Source code documentation</A>
</UL>
<LI><A NAME="tex2html22"
HREF="#SECTION00070000000000000000">6 Documentation formatting with HTML</A>
<LI><A NAME="tex2html23"
HREF="#SECTION00080000000000000000">7 Use LyX</A>
<LI><A NAME="tex2html24"
HREF="#SECTION00090000000000000000">8 What about PDF?</A>
<LI><A NAME="tex2html25"
HREF="#SECTION000100000000000000000">9 Conclusion</A>
</UL>
<!--End of Table of Contents-->
<P>
<H2><A NAME="SECTION00020000000000000000">
1 Introduction</A>
</H2>
<P>
Giving everything a GUI has become a popular trend in the Linux community.
This implies that more and more program authors tend to use a GUI-based
configuration dialog.
<P>
However, you lose an important thing when GUIs are used for everything:
documentation. People who can point-and-click
are often the one who think: ```Why should I read the programs
documentation? I simply point-and-click--and it works.''
<P>
But it would be better to encourage people to read documentation.
In fact, the better the documentation, the simpler it is to use
a program. Take the Apache web server for example, it comes
with heavy documentation. As a result, anybody who can understand a little
English is able to use Apache and configure it--without using a
point-and-click interface.
<P>
This article tries to encourage programmers to document their projects,
as well as to provide ideas and tips on doing so.
<P>
<H2><A NAME="SECTION00030000000000000000">
2 Why should I write documentation?</A>
</H2>
<P>
Lots of reasons! More documentation means easier usage. More documentation
means better add-on modules. More documentation means happier users.
As soon as a user gets stuck trying to get a program feature to work, he
or she starts to read that program's documentation. Imagine, therefore,
creating well-structured and well-written documentation that will make it
easy for the user to get that feature to work.
<P>
<H2><A NAME="SECTION00040000000000000000">
3 What aspects of my project/program should I document?</A>
</H2>
<P>
In general the following aspects of a program or project should be
documented:
<P>
<OL>
<LI>Basic usage is mostly covered in a man page.
</LI>
<LI>More advanced usage can be achieved by listing ALL configuration
options in the documentation and giving examples on how to use them
(take the very good Apache documentation for example).
</LI>
<LI>Source code, of course, because somebody may want to add features
to the program.
</LI>
<LI>Examples of usage to supply a working basic configuration file
and document it heavily.
</LI>
<LI>Installation of the program, because not all programs work with <B>./configure
&& make && make install</B>.
</LI>
<LI>User interface, especially if it is not a common point-and-click
one.
</LI>
</OL>
This list can be extended further. But in general a well-documented
program will cover at least these, and it will do so in a readable
fashion.
<P>
<H2><A NAME="SECTION00050000000000000000">
4 How do I write documentation?</A>
</H2>
<P>
Use your favourite text editor, as the formats I propose here can all
be written using a text editor.
<P>
Style is worth mentioning as well. Write your documentation in an
easy-to-read style. Do not try to use poetry.
<P>
The preferred language for documentation is plain English, as almost
anyone who uses a computer is able to understand it. You can always
add documentation in your native language as well. But keep in mind
that not everyone speaks German or Russian. At least include English
documentation for the most basic parts of your project. Someone who
cannot understand the simplest parts of the documentation will not read
it, and in many cases he will not use that program.
<P>
The rest is up to you. Always keep in mind that writing the documentation
is the ugliest part of developing.
<P>
<H2><A NAME="SECTION00060000000000000000">
5 What formats should I use for my documentation?</A>
</H2>
<P>
<H3><A NAME="SECTION00061000000000000000">
5.1 File formats suitable for documentation</A>
</H3>
<P>
Use a standard one, nobody likes proprietary file formats. This
effectively kills MS Word, StarOffice or anything like that for documentational
purposes.
<P>
The most simple format is plain text. It can be read everywhere, and
everyone can use his or her favourite pager or editor.
<P>
If you want your documentation to be printable, L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X is a good
choice. It is relatively easy to use, at least for writing a documentation
file. Advantages of using L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X are the system-independent
output format and a stylish formatted document. You can even export
it to HTML.
<P>
The most preferred choice nowadays is HTML. It is hypertext, there
are readers for all platforms available, and it can be distributed
on the project's homepage for on-line reading.
<P>
You can also use an SGML- or XML-based format such as DocBook or
LinuxDoc/SGML. These formats provide the most flexibility for converting
to many other output formats (including formats which haven't been invented
yet), or parsing as structured text (for automated text-processing tools),
but require a learning curve similar to
L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X.
<P>
<H3><A NAME="SECTION00062000000000000000">
5.2 Source code documentation</A>
</H3>
<P>
Source code can simply be documented by heavy use of comments and
suitable variable names. API descriptions in an external file is important,
especially if you're writing a library or something else that can
be extended.
<P>
<H2><A NAME="SECTION00070000000000000000">
6 Documentation formatting with HTML</A>
</H2>
<P>
Always use the most common subset of HTML. Do not use frames or Javascript
in documentation. Simply use <H1></H1> to <H6></H6> for sections and
<P></P> for paragraphs. Read your favourite HTML-Howto for more detail.
<P>
<H2><A NAME="SECTION00080000000000000000">
7 Use LyX</A>
</H2>
<P>
This my personal tip for writing program documentation. It features
what-you-see-is-what-you-mean input and result formatting in L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X,
as well as export to ASCII and HTML. Think of it as some sort of GUI frontend
for L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X. Always keep in mind that LyX is not a WYSIWYG
text processor</B>.
<P>
LyX comes with most Linux distributions, with its own
documentation file. Give it a try--it's easy to use and the results
are stunning.
<P>
The export features of LyX make it well-suited for our purpose.
You can create a .dvi file of your documentation that can be printed
on almost all Linux boxes configured for printing. So even
the distribution of a printable manual is easy.
<P>
<H2><A NAME="SECTION00090000000000000000">
8 What about PDF?</A>
</H2>
<P>
PDF is an extended version of Postscript. Its main disadvantage for
documentation is it requires a graphic display or a printer to
be viewed properly.
<P>
PDF is also less reliable on Linux. HTML files and man pages "just
work". L<SUP><SMALL>A</SMALL></SUP>T<SMALL>E</SMALL>X files work if you
install the software correctly. But there are incompatibilities between
the various PDF-authoring tools and viewers, and you may end up
distributing a document that somebody can't open or that has some of the
text showing up blank in various viewers.
<P>
PDF files are also huge, especially if you include pictures and tables.
Displaying PDF files is slow compared to HTML, DVI or plain
text. You may use it--but I do not recommend PDF for project documentation.
<P>
<H2><A NAME="SECTION000100000000000000000">
9 Conclusion</A>
</H2>
<P>
Writing documentation can be fun if you use the right tools. Always
remember that the documentation should be written so that anyone
can read it.
<P>
Now, go do it--good documentation is worth the effort.
<!-- *** BEGIN bio *** -->
<SPACER TYPE="vertical" SIZE="30">
<P>
<H4><IMG ALIGN=BOTTOM ALT="" SRC="../gx/note.gif">Matthias Arndt</H4>
<EM>I'm a Linux enthusiast from northern Germany.
I like plain old fifties rock'n'roll music, writing
stories and publishing in the <i>Linux Gazette</i>, of course.
Currently I'm studying computer science in conjunction with
economics.</EM>
<!-- *** END bio *** -->
<!-- *** BEGIN copyright *** -->
<P> <hr> <!-- P -->
<H5 ALIGN=center>
Copyright © 2001, Matthias Arndt.<BR>
Copying license <A HREF="../copying.html">http://www.linuxgazette.com/copying.html</A><BR>
Published in Issue 71 of <i>Linux Gazette</i>, October 2001</H5>
<!-- *** END copyright *** -->
<!--startcut ==========================================================-->
<HR><P>
<CENTER>
<!-- *** BEGIN navbar *** -->
<IMG ALT="" SRC="../gx/navbar/left.jpg" WIDTH="14" HEIGHT="45" BORDER="0" ALIGN="bottom"><A HREF="lg_tips71.html"><IMG ALT="[ Prev ]" SRC="../gx/navbar/prev.jpg" WIDTH="16" HEIGHT="45" BORDER="0" ALIGN="bottom"></A><A HREF="lg_toc71.html"><IMG ALT="[ Table of Contents ]" SRC="../gx/navbar/toc.jpg" WIDTH="220" HEIGHT="45" BORDER="0" ALIGN="bottom" ></A><A HREF="../lg_frontpage.html"><IMG ALT="[ Front Page ]" SRC="../gx/navbar/frontpage.jpg" WIDTH="137" HEIGHT="45" BORDER="0" ALIGN="bottom"></A><A HREF="http://www.linuxgazette.com/cgi-bin/talkback/all.py?site=LG&article=http://www.linuxgazette.com/issue71/arndt.html"><IMG ALT="[ Talkback ]" SRC="../gx/navbar/talkback.jpg" WIDTH="121" HEIGHT="45" BORDER="0" ALIGN="bottom" ></A><A HREF="../lg_faq.html"><IMG ALT="[ FAQ ]" SRC="./../gx/navbar/faq.jpg"WIDTH="62" HEIGHT="45" BORDER="0" ALIGN="bottom"></A><A HREF="joshi.html"><IMG ALT="[ Next ]" SRC="../gx/navbar/next.jpg" WIDTH="15" HEIGHT="45" BORDER="0" ALIGN="bottom" ></A><IMG ALT="" SRC="../gx/navbar/right.jpg" WIDTH="15" HEIGHT="45" ALIGN="bottom">
<!-- *** END navbar *** -->
</CENTER>
</BODY></HTML>
<!--endcut ============================================================-->
|
