Home
Overview
Search
Mailing lists
Forum
FAQ

Documentation

Well written documentation can make all the difference in whether a software package is used by anyone other than its developers.

Well written documentation also helps sponsors and potential sponsors evaluate a package. Documentation that is integrated into the release via html pages can also help

Software documentation can be split into several categories

Installation

The Installation documentation should usually has two distinct sections:

one section for experienced installers, who just want the facts in a concise manner.

one section for less experienced users. A troubleshooting section can help here.

The installation documentation should include a list of the requirements of the software, and should be visible from the download page so that users can see what they need to do after downloading the software.

If the installation procedure is very similar to other software, then there are likely to be far fewer problems. Ideally ./configure; make; make install should be all that is necessary.

User Level

User level documentation consists of information about what the package does, and how to run the demonstrations.

User documentation is sometimes written using MS Word or Framemaker, and shipped as a PDF file, or a collection of HTML files.

Programmer Level

Programmer documentation is for software developers who want to extend the software system, or include the system in their own package.

The code itself should be considered a publication, each file should have the following

A copyright notice

A primary author

A list of contributors

A version control tag such as

Version: $Id: docs.htm,v 1.7 2004/11/15 02:38:11 cxh Exp $

so that each file can be associated with a branch in the tree

The source files should have a common style

The files should be spell checked

Programmer documentation usually includes class and method documentation. Using an embedded documentation system can be a big win in this area.

Java code should use the javadoc system to generate readable html documentation.

C++ code should probably use a similar embedded system

Online Help

Providing well thought out online help, error handling and error messages can greatly improve the user's experience.

The Java exception handling mechanism should be used properly. Software packages should define exceptions and use them.

Documentation formats

Documentation is usually in several formats:

Text: ASCII Text files are useful for short files. CVS takes care of the newline issues, but shipping tar and zip files can be a little tricky.
HTML: HTML files are the preferred format, especially for Java packages that include applets.
PDF: PDF is the preferred platform neutral format for longer documents such as user guides.
PostScript: PDF is preferred over PostScript. Adobe Distiller can be used to convert PostScript to PDF. The GSRC has a copy of Distiller.
Microsoft Word and Framemaker files: These formats are vendor specific and are not usually shipped with a release. It is far better to ship PDF files, or convert the document into HTML. Word and Frame files can be checked into the CVS repository with the -kb option.

Common Documentation Problems

Below is a checklist of common documentation problems.

Spelling Errors

Use a spell check program.

Ptolemy II includes $PTII/util/testsuite/ptspell, which is hacked up to split up mixed case words like "inputPort" and spell check the pieces.

If need be convert the pdf file to text and spell check it.

Incorrect citation

All papers should include the proper citation for that paper.
Ideally, include a "cite as" section.

At UC Berkeley, if a paper is not part of a journal or book, then it should be submitted as an ERL Memorandum, and the memorandum number should be included in the paper.

Be sure to include the institution name and the date.

Contact Information

Consider including contact information for one of the authors on the paper

No Abstract

Do your users and yourself a favor and include an abstract.

Copyright

Unless a paper is a rereleased version of a previous paper, it should be copyrighted with the current year.
See the Copyrights Page for details

Acknowledgements

Sponsors like to see their names up front on the front page. See the GSRC Word Template page for sample acknowledgement code.

If the paper is long, consider adding a table of contents.

Example Code

Example code should make good use of whitespace.
Spaces should follow commas.
Comments should be complete sentences.

Diagrams

The best diagrams are vector based diagrams because they reproduce very well at different resolutions. jpgs of text should be avoid because of jaggies and lossy behaviour.

Style

If you have not read Strunk & White lately, please do so.

Strunk, William. Elements of Style. Ithaca, N.Y.: Priv. print. [Geneva, N.Y.: Press of W.P. Humphrey], 1918; Bartleby.com, 1999

The American Heritage Book of English Usage. Boston: Houghton Mifflin, 1996

Watch out for using "which" when you mean "that" . Grammar: Traditional Rules, Word Order, Agreement, and Case, 62. that

One hack for checking style is to import your document into Microsoft Word and check the grammar.
The Microsoft Word grammar checker is not foolproof, but you should understand each problem it reports.

The following script uses pdftotext from The Xpdf project to convert PDF into a text format suitable for importing into Word.

#!/bin/sh
txtFile=`basename $1 pdf`txt
pdftotext $1 
 sed 's/^[ 	]*//' < $txtFile | \
    awk '{if ($0 ~ /-$/) {printf("%s", substr($0,0,length($0)-1))} else {print $0}}' | \
    awk '{if (length($0) == 0) {print $0} else {printf("%s ", $0)}}' \
    > pdf2textTmp.txt
cp pdf2textTmp.txt $txtFile

rm -f  pdf2textTmp.txt

Bibliography

Make sure that the Bibliography is correct.
Check the source material for the proper names, name order, title etc.

Submit it to the GSRC Website

Papers discussing GSRC sponsored research should be submitted to the GSRC Website.

You are not logged in