343 lines
12 KiB
HTML
343 lines
12 KiB
HTML
<!--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="index.html"><IMG ALT="[ Table of Contents ]" SRC="../gx/navbar/toc.jpg" WIDTH="220" HEIGHT="45" BORDER="0" ALIGN="bottom" ></A><A HREF="../index.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="../faq/index.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="index.html"><IMG ALT="[ Table of Contents ]" SRC="../gx/navbar/toc.jpg" WIDTH="220" HEIGHT="45" BORDER="0" ALIGN="bottom" ></A><A HREF="../index.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="../faq/index.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 ============================================================-->
|