Documentation for user defined packages and Macaulay2 itself is written using two main methods:
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.
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.
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.
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.