writing documentation

Documentation for user defined packages and Macaulay2 itself is written using two main methods:

Macaulay2 documentation methods

• the document(List) function, using a list-based hypertext markup format;
• the doc(String) function, using a string-based SimpleDoc format.

It is then formatted via installPackage as the documentation built into Macaulay2, the online HTML documentation, and the info pages. Much of the format and structure of the documentation is automatically generated. Each documentation entry must be part of a package, and occur after the beginDocumentation section of the package.

Documentation templates

Each documentation entry is either an overview topic, or documentation of an individual feature, such as a symbol, a function name, a function call (that is, a function name, together with specific types of its arguments), an optional argument to a function, or a package.

The easiest way to write documentation for an entry is to start with an example as a template. See the documentation on either of the documentation methods above for templates and examples.

The documentation writing cycle

Start with the package that you wish to document, and select one or several of the above examples or templates. Cycle through the following steps as you refine your documentation.

0. Edit your documentation entries as desired
1. Generate the html pages for your package, using

   installPackage("YourPackage")

2. Review the generated HTML documentation using viewHelp which displays this page in a browser.

Documentation style conventions

There are a few stylistic conventions that should be noted. While not hard and fast rules, keeping these stylistic conventions in mind makes for easier reading by users.

• Lowercase is used for all titles, unless a proper noun is being used.
• Use TO to reference any Macaulay2 function, option, or variable occurring in the documentation as a hyperlink.
• Inputs, Outputs, and Consequences should not end with periods.