This guide provides an overview of the Mandolin Creek System Helper (MCSH) documentation policies, syntax, style, and tools.
The MCSH package provides several kinds of documentation, listed here in descending order of authority:
- The source code: You should never blindly trust any documentaion. Period.
- Developer's Reference Manual: Generated directly from the source code comments, this form of documentation provides an easy-to-digest format for developers that need to frequently reference the MCSH libraries and internals. Plus, there are lots of fancy graphs.
- User Scripting Guide: This document targets users that want to customize or extend scripts.
- User Guide: Without users, what's the point of it all? Right? Can I get an 'Amen, Brother!' from the choir?!
The MCSH package embraces all of the policies in this section. The use of words such as must, should, and may in this section seek to reflect the same level of precision in the specifciation of these policies as one would expect from an RFC.
All MCSH documentation must adhere to the policies in this section, regardless of its audience or topic:
- All documentation must be written in literate English.
- All documentation source must be stored in plain text files on disk.
- All documentation should hedge toward accuracy over precision, but both are preferred.
In addition to those basic requirements, all documentation intended to be consumed by end users must follow these policies:
- All documentation should be readable by users with a high school education.
Everything listed below must be documented:
- Source code
- Applications
- Workflows
- Use cases
- Designs
- Architecture
All documentation must be written in a suitable format:
- All documentation formats must have a native idempotent text format.
- All simple documentation must be written in reStructuredText. In this context, "simple" can be defined as "within the capabilities of the reStructuredText markup".
- Documentation that exceeds the capabilities of reStructuredText must be written in LaTeX.
- Some documents should be referenced rather than being generated or converted into a suitable format. Examples include PDFs, images, or other externally produced binary files.
- External references and non-generated binary documentation files must be kept to an absolute minimum.