Package Documentation Style

"I have no idea what you think I need. You need subtitles. Or some kind of instruction manual."

Neil Gaiman, Death: The High Cost of Living

These guidelines are for documenting software distributions of open source software. They are applicable to C, Perl, and Java projects, and even projects that may not contain any compiled software. These guidelines do not cover web pages or other sorts of external documentation apart from what's included in the distribution tarball.

Package Documentation Files

Any application should contain, at the top level, the following documentation files:

LICENSE Collected licensing information for the package
NEWS User-visible changes (see below for format)
README A brief description of the package and contact info
TODO Things yet to be done

If the installation instructions are extensive, one may optionally separate the installation section out into an INSTALL file and refer to it in README.

The preferred format for these documentation files is plain text.

Every package should be released under some particular license, even if that license is just "no redistribution without my explicit permisison." That license should be stated at the top of LICENSE along with the general copyright for the whole package. The remainder of the LICENSE file should contain the collected copyright notices and then licensing information for each included file. The syntax of this file is in flux and will probably eventually switch to the Debian DEP-5 format, once that's finalized.

NEWS Format

The NEWS file should document user-visible changes to the package. The preferred format looks like:

    package 1.3 (2002-10-03)

        Description of changes in that release.

    package 1.2 (2002-08-20)

        Description of changes in that release.

and so forth. In other words, a series of headings giving the package name, version, and date of release, and then indented paragraphs describing the user-visible changes that went into that version. The descriptions should be brief and intended for the user of the package; purely internal changes don't need to be documented except in the commit messages.

To record changes that aren't yet in a released version, add a new header for the expected next version of the package, with a version number increase based on the level of changes that have been integrated so far, but with (unreleased) after the version number instead of the date.

README Format

In README, the body text should indented by a few spaces and the headers starting at the left margin. This format converts well to HTML with automated tools but is still very easy to edit. I usually use two spaces of indentation in the README files where each section is short enough to not require subsections, and four spaces if subsections are required, with subheadings indented by two spaces.

The README file should start with a centered header stating the package name and version and then a centered short description in parenthesis on the next line. After a blank line should come the authorship and maintainer information, also centered. Then, the general copyright statement and a pointer to LICENSE should come next. For example:

                           package release 2.16
                      (short description of package)

                    Originally written by Some Author
          Currently maintained by Russ Allbery <eagle@eyrie.org>

    Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Russ
    Allbery <eagle@eyrie.org>.  This software is distributed under a
    BSD-style license.  Please see the file LICENSE in the distribution
    for terms of use and redistribution.

The last paragraph is normally indented by two spaces.

After that introduction, README should normally contain the following sections:

BLURB

A one-paragraph brief description of the software package and why it's useful. This paragraph is the first paragraph of every release announcement, so it should be kept succinct and to the point. It's usually also used as the package description in any Debian package.

DESCRIPTION

The longer description of the package. Include discussion of all the components, possibly something about the history of the package, and any pointers to additional package documentation that the user may be interested in. Use subsections if there's a lot to discuss.

REQUIREMENTS

List all software requirements to use or build this software, including any optional components and optional dependencies. Don't forget to include a list of software required to bootstrap from revision control or needed if one wants to modify the configure script or Automake makefile.

INSTALLATION

Describe the package build and installation procedure, including any configure arguments. Look at other packages for things one can copy and paste here, since things like the Kerberos library flags should use the same wording in every package.

TESTING

Describe the test procedure. Omit this section if there's no test suite. I try to use C TAP Harness for all test suites, and use the same description for how to run that test suite across all packages. If this is particularly short, it can be combined with the INSTALLATION section.

HOMEPAGE AND SOURCE REPOSITORY

A pointer to the package home page (if any) and to the publicly accessible revision control repository (if any), including any special instructions on how to check out the source code. Give both the revision control URL and the web viewer URL.

THANKS

Thanks for major contributions to the package. This doesn't need to list everyone who did anything on the package, since people should be thanked in NEWS. But listing major contributions is good. If this section gets particularly long, break it out into a separate THANKS file.

Program Documentation

Every non-trivial program should have a manual page. The best way to maintain a manual page is to write it in POD, rather than trying to maintain nroff by hand, since more people are likely to know POD and it's faster to pick up. To learn about POD, read man perlpod. It's also worth reviewing the POD documentation for other programs that we've already written to get a feel for the formatting style.

In short: Any program switches should be enclosed in B<>, any user-supplied options should be enclosed in I<>, and any references to the command itself should be enclosed in B<>. References to files, such as configuration files, should be enclosed in F<>.

The documentation should at a minimum include NAME, SYNOPSIS, DESCRIPTION, EXAMPLES, AUTHOR or AUTHORS, and COPYRIGHT AND LICENSE sections in that order. If it has any command-line options, there should also be an OPTIONS section immediately following the DESCRIPTION section. These should all be =head1 sections in POD.

The NAME section should consist solely of a single line containing the program name, a space, a single dash, a space, and a brief one-line description of what it does. That description must fit on a single line. This section is treated specially by man reading programs, so stick to this syntax religiously.

The SYNOPSIS section should describe the command-line syntax of the program. The DESCRIPTION section should describe in detail what the program does.

The OPTIONS section should be an =over 4 list of options, each one introduced with an =item line, closed with =back.

There are additional sections that are often useful or desirable, including FILES, ENVIRONMENT, DIAGNOSTICS, SEE ALSO, WARNINGS, etc. For additional information on how to write good man pages, see man pod2man.

The man page should then be generated automatically from the POD in autogen at the top level of the source tree. A typical command to put in that file is:

    version=`grep '^kstart' NEWS | head -1 | cut -d' ' -f2`
    pod2man --release="$version" --center="kstart" k5start.pod > k5start.1

Notice how the version number is extracted from NEWS. --release and --center (-r and -c; the spelled-out versions may be preferrable if longer) should always be set, since the defaults assume that the command is part of the currently installed version of Perl.

Last modified and spun 2015-11-01