Skip to content

How I Document

Here are the tools I use:

MkDocs#

I use MkDocs + MkDocs Material.

I have a few dislikes:

  • The mkdocs-material theme turns 50% 1080p displays to mobile. I have fixed this in my fork.
  • mkdocs-material is EOL November 2026. (I'm not worried, it's a SSG)

Ultimately I find it a workable solution for the time being, it searches well, highlights code, and works well in CICD to generate this very site!

Read here for my common snippets: link

VSCode Documentation Setup#

I use VSCode with a few plugins to help:

  • Notes to keep my mkdocs project always accessible.
  • Todo Tree to manage stubs for things I'll insert later.
  • Paste Image to paste images.
  • A few global markdown snippets to make mkdocs management easier.

My config can be found here.

Recording & Capture#

I use as little tools as possible and keep it as close as possible to immediate capture and record.

Product What
Kdenlive Video Editor + Screen Recorder
Glaxnimate Basic Animation Tool
ZoomIT Windows Image Annotation
KDE Linux Image Annotation and Screen Recording

Documentation Strategy#

I do a simple 1st pass -> 2nd pass system.

The 1st pass is just the minimal amount of notes needed at your current skill level.

We're trying to knock out a feature in one run to catch issues ahead of time.

  • Record only things you find important that aren't obvious to you.
  • Screenshot only things hard to reproduce efficiently.
  • Keep it in one file.
  • Use TODOs for good ideas later.

1st Pass Example:

# Install Apache Procedure & Test
pacman -S apache
sudo systemctl start httpd
sudo systemctl enable httpd

will be blank with dir on.

<TODO: SCREENSHOT>

Add to root `/srv/http/index.html`

sudo vi /srv/http/index.html

verify show up http://localhost/ - Done

# Notes
https://wiki.archlinux.org/title/Apache_HTTP_Server

---

# Configuration Procedure
...

We will do our 2nd pass in bulk once we're ready to stop our 1st pass.

Include:

  • Rich media (Screenshots, images, graphs, flowcharts).
  • Use case / why / problem statement.
  • Expanded sections & article splitting.
  • Conditionals (issues, failures, warnings).
  • Prerequisites / state of installation (if necessary).

Be quick and add only what makes sense from the above, let people tell you what could help later.

2nd Pass Example:

## What

We will be installing Apache2 (also known as `apache` or `httpd`) on Arch Linux.

## Prerequisites

Install `apache`

```bash
sudo pacman -Syu # If you haven't already updated your system
sudo pacman -S apache
```

We will need to enable Apache via Systemd:

```bash
sudo systemctl start httpd
sudo systemctl enable httpd
```

We should now see a webpage on our web browser: http://localhost

![](../assets/images/image-20251207120026.png)

## Modify Root

By default, Apache on Arch will display a blank directory page.

We can add pages to Apache by modifying `/srv/http/`.

Let's add a default index.html:

```bash
sudo nvim /src/http/index.html
```

We'll use a simple Hello World HTML page:

```html title="/src/http/index.html"
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Hello, World!</title>
</head>
<body>
    <h1>Hello World!</h1>
    <p>This is my first web page.</p>
</body>
</html>
```

Let's revisit our web server, which should now be our index.html: http://localhost

![](../assets/images/image-20251207121437.png)

You have successfully setup Apache and created a web page.

## Extra Notes

Arch Wiki: https://wiki.archlinux.org/title/Apache_HTTP_Server

Now consider the following scenarios:

  • What if /srv/http/ was not the correct folder?
  • What if apache was deprecated and apache-fixed looked different?
  • What if our target audience is a pro team?
  • What if nginx is what we really needed?

Doing a 1st pass mitigates time loss by pushing discovery first.

Just remember to clean up the documents and publish them ASAP.

When we take risks early and return back to it same-day, we learn more and save time.