Doc tools

[bzm3r]

Project description

Writing documentation is not easy for a variety of reasons.

A small proportion of these reasons could be tackled through tooling, some of it automated. These are typically issues that occur when one sits down to write documentation. Here are some examples:

• Workflow checklists: complete with links, that make it easy for a documentation writer to know they are following best practices, and to look up information regarding particular parts of the process. These can be thought of as improvements to the usual contributing guidelines. They should accommodate continuous improvement of process (i.e. they are far from static), and identification of pain points that could be automated.

• Macros: tools to reduce manually executed repetitive actions, such as copying-and-pasting, verifying against a terminal, etc.

• Find-and-replacers: tools that make it easy to implement a simple custom syntax for representing a particular concept, and then replace that custom syntax with (usually more verbose) standard syntax.

These tools need not be complicated, and should aim for simplicity. To this end they ought to

• be CLI tools
• well documented, and preferably, automatically documented by incorporating docstrings
• written in a strongly typed, statically compiled language with good IDE support
• support manual invocation on input by default

Steps

• Example generator
• Hyperlinker