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 package source code: You should never blindly trust any documentaion. Period.
Developer Reference: 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.
- Developer Guides: Generated directly from the docs/ directory
in the MCSH source package.
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.
The following polices have been adopted as strategic temporary measures.
- All documentation should presume adminstrators know how to operate the external programs that underpin the MCSH scripts.
These policies be revised at some point in the future, once the system reaches certain milestones that force them to be changed.
The MCSH scripts have many different potential audiences, and each audience come from drastically different backrounds. At the same time, each user may want to use different sets of features in the MCSH package. The MCSH documentation must serve all of these backgrounds and purposes, assisting users with the progression from basic usage all the way to custom system development and deployment.
All MCSH users, from the newest user to the project's author, execute its tools with a specific intention. These intentions can be divided into clearly idenfifiable user roles:
- System Maintainer: Uses MCSH to improve and maintain MCSH itself.
- System Developer: Uses MCSH to develop a custom MCSH deployment.
- Script Developer: Uses MCSH by extending or writing scripts to perform tasks for their own work.
- System Administrator: Uses MCSH for system deployment, hosting, security, and other administration tasks.
- Office User: Uses MCSH Paperless Office extensions.
- End User: Uses MCSH tools for purposes unrelated to any of the above roles.
In addition to the above list of roles, end users of the MCSH IDE can be divided meaningfully into several other roles:
- Package Maintainer: Uses MCSH to create and maintain a package.
- Package Developer: Uses MCSH to develop a package.
- Package User: Uses MCSH to build and install a package.
As MCSH itself uses the MCSH IDE, all MCSH users act in the role of Package User when building and installing it.
This section describes the requirements when writing documentation for different types of users.
All documentation must be structured and written in a way that accounts for the differing levels of expected technical expertise associated with these roles.
TODO
In addition to the basic content requirements, all documentation intended to be consumed by end users must follow these policies:
- User content should be readable by users with a high school education.
- User content should presume users know how to use their operating system
TODO
In addition to the basic content requirements, all documentation intended to be consumed by system administrators must follow these policies:
- All documentation should presume adminstrators know how to operate the external programs that underpin the MCSH scripts.
- Each external program utilized must be documented, with links to documents that were used to develop MCSH support.
TODO
TODO
TODO
TODO
TODO
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.
In simpler terms, this means that the contents much be fully readable (plain) text, and that contents must not change when re-saved without introducing actual changes. This prohibits binary formats and text formats that include metadata that is always modified upon saving (e.g. OpenOffice).
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 formatting or expressive capabilities of reStructuredText must be written in LaTeX.
Some documents should be referenced rather than being generated in a text format (or idempotently converted to one). Examples include PDFs, images, or other intrinsically binary files.
External references and non-generated binary documentation files must be kept to an absolute minimum.