version 1.1, 2009/03/22 08:52:27 |
version 1.6, 2009/03/22 20:55:18 |
|
|
.Dd $Mdocdate$ |
.Dd $Mdocdate$ |
.Dt "Writing Unix Documentation" paper |
.Dt manuals 7 |
.Os |
.Os |
|
.\" SECTION |
.Sh NAME |
.Sh NAME |
.Nm Writing Unix Documentation |
.Nm Writing UNIX Documentation |
.Nd a guide to writing Unix manuals |
.Nd a guide to writing UNIX manuals |
|
.\" SECTION |
.Sh DESCRIPTION |
.Sh DESCRIPTION |
<h1> |
.Em A utility without good documentation is of no utility at all . |
Writing Unix Documentation |
.\" PARAGRAPH |
</h1> |
.Pp |
|
A system component's documentation describes the utility of that |
|
component, whether it's a device driver, an executable or, most |
|
importantly, a game. Although there are plenty of documents available |
|
on how to read |
|
.Ux |
|
documents, or where to find them, few focus on composition. |
|
.\" PARAGRAPH |
|
.Pp |
|
This document serves as a tutorial to writing |
|
.Ux |
|
documentation |
|
.Pq Dq manuals . |
|
If you add something to your operating system, whether it's a new file |
|
format or directory structure or device driver, it needs documentation. |
|
.\" SECTION |
|
.Sh COMPOSITION |
|
Prepare your composition environment by copying over the manual template |
|
from |
|
.Pa /usr/share/misc/mdoc.template . |
|
.Em \&Do not |
|
start afresh or by copying another manual unless you know exactly what |
|
you're doing! |
|
.\" SUBSECTION |
|
.Ss Section Numbering |
|
Find an appropriate section for your manual. There may exist multiple |
|
manual names per section, so be specific. A table of all available |
|
manual sections follows: |
|
.Pp |
|
.\" LIST |
|
.Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact |
|
.It Em Section |
|
.Em Description |
|
.It 1 |
|
operator utilities |
|
.It 2 |
|
system calls |
|
.It 3, 3p, 3f |
|
programming libraries (C, Perl, Fortran) |
|
.It 5 |
|
file and wire protocol formats |
|
.It 6 |
|
games |
|
.It 7 |
|
tutorials, documents and papers |
|
.It 8 |
|
administrator utilities |
|
.It 9 |
|
in-kernel routines |
|
.El |
|
.Pp |
|
If your manual falls into multiple categories, choose the most |
|
widely-used or, better, re-consider the topic of your manual to be more |
|
specific. You can list all manuals per section by invoking |
|
.Xr apropos 1 , |
|
then provide the |
|
.Fl s |
|
flag to |
|
.Xr man 1 |
|
to see the specific section manual (section 1, in this example): |
|
.\" DISPLAY |
|
.Bd -literal -offset indent |
|
% apropos myname |
|
myname (1) - some description here |
|
% man \-s 1 myname |
|
.Ed |
|
.\" SUBSECTION |
|
.Ss Naming |
|
Name your component. Be terse, erring on the side of clarity. You may |
|
want to look for other manuals by that same name before committing: |
|
.Pp |
|
.Dl % apropos myname |
|
.Pp |
|
Manual files are named |
|
.Pa myname.mysection , |
|
such as |
|
.Pa manuals.7 |
|
for this document. |
|
.\" SUBSECTION |
|
.Ss Input Language |
|
Manuals should |
|
.Em always |
|
be written in the |
|
.Xr mdoc 7 |
|
formatting language. |
|
.Pp |
|
There exist other documentation-specific languages, such as the |
|
historical |
|
.Xr me 7 , |
|
.Xr ms 7 |
|
and |
|
.Xr man 7 |
|
packages of |
|
.Xr roff 7 ; |
|
newer languages such as DocBook, texinfo or schema-driven XML; or even |
|
ad-hoc conventions such as README files. |
|
.Em Avoid these formats . |
|
Historical formats fail to capture a manual's semantic content, instead |
|
only modelling its style. Newer methods requires special, |
|
system-specific tools and may change or become obsolete over the |
|
life-time of your component. |
|
.Pp |
|
There are two canonical references for writing mdoc. Read them. |
|
.Pp |
|
.\" LIST |
|
.Bl -tag -width XXXXXXXXXXXXXXXX -offset indent -compact |
|
.It Xr mdoc 7 |
|
formal language reference |
|
.It Xr mdoc.samples 7 |
|
macro reference |
|
.El |
|
.Pp |
|
Open the template you've copied into |
|
.Pa name.section |
|
and begin editing. |
|
.\" SUBSECTION |
|
.Ss Development Tools |
|
While writing, make sure that your manual is correctly structured: |
|
.Pp |
|
.Dl % mandoc \-Tlint \-Wall name.1 |
|
.Pp |
|
You may spell-check your work as follows: |
|
.Pp |
|
.Dl % deroff name.1 | spell |
|
.Dl % ispell \-n name.1 |
|
.Pp |
|
Use |
|
.Xr cvs 1 |
|
or, if not available, |
|
.Xr rcs 1 |
|
to version-control your work. If you wish the last check-in to effect |
|
your document's date, use the following RCS tag for the date macro: |
|
.Pp |
|
.Dl \&.Dd $Mdocdate$ |
|
.\" SUBSECTION |
|
.Ss Viewing |
|
mdoc documents may be paged to your terminal with traditional |
|
tools such as |
|
.Xr nroff 1 , |
|
.Xr groff 1 , |
|
or with newer, more powerful tools such as |
|
.Xr mandoc 1 : |
|
.\" DISPLAY |
|
.Bd -literal -offset indent |
|
% nroff \-mandoc name.1 | less |
|
% groff \-Tascii \-mandoc name.1 | less |
|
% mandoc name.1 | less |
|
.Ed |
|
.Pp |
|
Other output formats are also supported: |
|
.\" DISPLAY |
|
.Bd -literal -offset indent |
|
% groff \-Tps \-mandoc name.1 | less |
|
% mandoc \-Thtml name.1 | less |
|
.Ed |
|
.\" SUBSECTION |
|
.Ss Automation |
|
Consider adding your mdoc documents to |
|
.Xr make 1 |
|
Makefiles in order to automatically check your input and generate |
|
output: |
|
.Bd -literal -offset indent |
|
\&.SUFFIXES: .html .txt .1 .in |
|
|
<p> |
\&.in.1: |
<span class="attn">A utility without documentation is of no utility at all.</span> |
mandoc -Wall,error -Tlint $< |
</p> |
cp -f $< $@ |
|
\&.1.html: |
<p> |
mandoc -Thtml $< >$@ |
A system component's documentation describes the utility of that component, whether it's a device |
\&.1.txt: |
driver, an executable or, most importantly, a game. Although there are plenty of documents available on |
mandoc -Tascii $< | col -b >$@ |
how to <i>read</i> Unix documents, or where to find them, few focus on how to <i>write</i> them. |
.Ed |
</p> |
.\" SECTION |
|
.Sh BEST PRACTICES |
<p> |
The |
This document serves as a reference guide to writing Unix documentation. If you add something to your |
.Xr mdoc 7 |
operating system, whether it's a new file format or directory structure or device driver, it needs |
and |
documentation. |
.Xr mdoc.samples 7 |
</p> |
files are indispensable in guiding composition. In this section, we |
</td> |
introduce some |
</tr> |
.Ux |
<tr> |
manual best practices: |
<td> |
.\" SUBSECTION |
<div class="foot"> |
.Ss Language |
Copyright © 2009 Kristaps Džonsons, $Date$ |
.Bl -enum |
</div> |
.It |
</td> |
Use clear, concise language. Favour simplicity. |
</tr> |
.It |
</tbody> |
Write your manual in non-idiomatic English. Don't worry about |
</table> |
Commonwealth or American spellings \(em just correct ones. |
</body> |
.It |
</html> |
Spell-check your manual, keeping in mind short-letter terms ( |
|
.Xr iwi 4 |
|
vs. |
|
.Xr iwn 4 ) . |
|
.It |
|
If you absolutely must use special characters (diacritics, mathematical |
|
symbols and so on), use the escapes dictated in |
|
.Xr mdoc 7 . |
|
.El |
|
.\" SUBSECTION |
|
.Ss References |
|
Other components may be referenced with the |
|
.Sq \&Xr |
|
and |
|
.Sq \&Sx |
|
macros. Make sure that these exist. If you intend to distribute your |
|
manual, make sure |
|
.Sq \&Xr |
|
references are valid across systems (within reason). If you cross-link with |
|
.Sq \&Sx , |
|
make sure that the section reference exists. |
|
.\" SUBSECTION |
|
.Ss Citations |
|
Cite your work. If your system references standards documents or other |
|
publications, please use the |
|
.Sq \&Rs/Re |
|
block macros. |
|
.\" SUBSECTION |
|
.Ss Formatting |
|
.Em Don't style your manual. |
|
Give it meaningful content. The front-end will worry about formatting |
|
and style. |
|
.\" SECTION |
|
.Sh MAINTENANCE |
|
As your component changes and bugs are fixed, your manual may become out |
|
of date. You may be tempted to use automation tools like Doxygen to |
|
smooth the development of your manuals. Don't. Source documentation is |
|
different from a component manual. |