Taking Notes#

Natural sciences are opinionated about keeping a lab notebook, often prohibiting students from using pencils to discourage mutation (ahem). Vitrina suggests looking for the equivalent in software, an opinionated method to * conserve all user input (shell commands, URLs) * save all my results (console output, results, error logs) * conserve all my references (links to diagrams, API definitions, etc) * support cross-reference or dynamic links to other sources (eg. avoid retyping or copy/paste)

Re-use immutable content#

A number of methods (eg. diataxis) suggests four kinds of documents:
  • Howto

  • Descriptions

  • References

  • Changes

To these four, we add two more for the control plane:
  • Automation (orchestration, dependencies)

  • Instrumentation (logs, metrics)

For example the project blog is based on a text file which serves as the input collector. From there, content will make its way into several categories.