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.

https://getnikola.com/handbook.html#jupyter-notebook-metadata