Skip to content

Documentation

This section captures how I have made (and changed) the ways I organise my notes for this website, as a documentation system.

  • I am using my notes mostly to document concepts, designs, and implementations of information technology. Therefore, I want to be able to include diagrams and source code in my notes and documentation.

  • I find the Diátaxis Framework is a helpful structure content to divide content into four categories: explanations, tutorials, how-to guides, and references. It helps me focus on a key question: what is this page trying to achieve?

  • Both for software documentation, as well as for personal knowledge management, having notes available in a plain-text format makes them usable with multiple tools. Also, the mental models and practices align well with those in software development. That makes the overal experience working on notes and documentation easier and more efficient.

Other context, other choices

Of course, you can have different needs, and make very different choices.

For instance, you may need a more detailed definition of what your content must look like, have more and stricter validation or access control mechanisms, a wider variety of output formats, and so on.

As a starting point, I would advise to look for something close to the mental model that people already use in organising their work, and integrate from there.

Explore