Guidance on new program documentation and test

For newly created programs, some documentation and test work items should be created, to aid the end-user and future program maintainers. In creating these docs and tests, it is best to take off your 'developer' hat, and put on your 'end-user' hat, and then your 'maintainer' hat, to gain the view point of someone who has never seen or worked with your program. Your program is new to the end-user or maintainer, and nothing should be assumed about what they know about how it works.

There are three main work items to create: end-user documentation, maintainer documentation, and test code.

End-user documentation

The primary (and typically only) end-user documentation to create is text information like what you see in a unix 'man' page. In freesurfer, as of Feb 2011, the code in the dev tree and v5.1 branch supports putting 'man page'-like information in an xml file, which is then embedded into the .c/.c++/csh program and printed for you in a nice format (also supports automatic creation of a wiki page and pdf doc, TBD). Detailed instructions on how to do this are here. To see some nice examples of this help text output, type:

mri_convert --help

or for a simpler example:

mris_inflate --help

But first, to keep things simple and ignoring those instructions and XML for the moment, using your favorite text editor, create a text file containing the follow sections:

Guidance on new program documentation and test

End-user documentation

Name

Synopsis

Description

Positional Arguments

Required Flagged Arguments

Optional Flagged Arguments

Example(s)

Reference(s)

Reporting

See Also

Maintainer documentation

Testing