Skip to content

System view

Let's look at the scope of the documentation system described in these notes. It consists of systems and user roles. In a diagram, it looks like this:

Documentation systemEditing tool Produces contentContent repository Manages versionsWebsite generator Builds the websiteEditor Adds contentPublisher Updates the websiteInterface template Defines the look and feelWebsite host Publishes the contentcontentcontentwrites withpreviews withstyleconfigures and runspublisheswebsite
Documentation systemEditing tool Produces contentContent repository Manages versionsWebsite generator Builds the websiteEditor Adds contentPublisher Updates the websiteInterface template Defines the look and feelWebsite host Publishes the contentcontentcontentwrites withpreviews withstyleconfigures and runspublisheswebsite

User roles

Editor
An editor contributes documentation content sources (text, diagrams) using editing tools. An editor can also preview the output, using the website generator.
Publisher
A publisher configures how the website will be built, adapting the interface template, building the website using the generator, and publishing the website.

Obviously, for my own notes, I act in both roles.

Outside the scope of this documentation

  • An editor will usually also manage content versions in the content repository.

  • Building and publishing the website can also be automated.

Systems

Editing tool
In this documentation, I will show how I work with Obsidian and VS Code, but an editor can choose other (even multiple) tools to write content with.
Content repository
The content repository is typically a Git repository, as used for source code management. I will only describe how I combine the content and configuration in a single repository.
Multiple repositories:

In software projects, implementation-specific and detailed documentation should ideally live inside the source code repository for the parts they describe.

This docs as code approach makes it easier for developers to keep the documentation up to date.

Also, the sources for the complete documentation are typically spread over multiple repositories.

On top of that, the documentation usually covers multiple versions.

I have worked with such setups in the past, but have chosen a simpler setup for my digital notes.

More on that will follow in a separate page.

Interface template
The interface template defines the layout and styling of the website. In my case, the content and the interface adaptations live in the same Git repository. Also, the interface is largely defined as part of the website generator.
Website generator
The website generator combines content sources and the interface template into a single website. This is a static website, that can be published almost anywhere. It also provides a preview version, to check the output before it gets published.
Website host
The website host makes the static website available on the web, independent of the the documentation system. The actual process of publishing the website is outside the scope of this documentation.