All posts

Knowledge Numbering & Catergories

A method of keeping track of all

This is a post that has been coming for a long while, but I've not had the time or real bandwidth to eke out all the details and refine them for others to use.

Over the years I've iterated through a number of different methods, styles and formats for keeping notes. I've used OneNote, Obsidian, flat markdown files, Google Drive, TiddlyWiki and Joplin, and I could go on. Ultimately I keep running into the same issue: how the heck do I categorise things so they make sense? How do I quickly find what I'm working on, or something I've written previously?

That seems to be the problem a lot of these tools attempt to solve but never fully get there. Sure, you can word search, or hope you added the right tags at the time, but that takes effort, and a spelling mistake or different phrasing means things get missed.

I looked into how others manage their own file systems and tried to adapt them to how I think. It's taken a while, because I'm a little weird!

Three jobs hiding inside "note-taking"

The first thing I worked out is that most of these systems solve different problems, and I'd been comparing them as if they were rivals. Think of a kitchen. How you chop the vegetables, how you lay out the pantry, and how you split the menu into starters and mains are three separate decisions.

How you write a note (capture)

  • Cornell splits the page into cues, notes and a summary, and is built around review. Good for lectures, less so for ops work.

  • Zettelkasten means atomic notes, one idea each, linked together rather than filed in folders. It comes from the sociologist Niklas Luhmann and his index cards. It's great for long-term research, but the overhead is high and the payoff is slow.

    Where a note lives (organisation)

  • PARA (Projects, Areas, Resources, Archive) sorts by whether something is actionable. It's worth knowing it's an organisation system rather than a note-taking method.

  • Johnny.Decimal gives everything a unique ID, with a hard cap on how many areas and categories you can have. Its own docs use the analogy of a filing cabinet, drawers and manila folders.

    What kind of document it is (type)

  • Diátaxis says documentation falls into four kinds, answering four different needs: tutorials, how-to guides, reference and explanation. Projects like Quarkus and Canonical build their docs around it. None of them gave me what I wanted on their own. Zettelkasten is lovely for ideas but not for "where's the runbook for the thing that broke on Tuesday". PARA is flexible, but "Resources" turns into a junk drawer. Johnny.Decimal came closest, because a fixed address means you never have to search. You just know where to look.

What I actually built

I wanted something with the permanence of an engineering document register, the sort of thing NASA-style programmes use, where every document has one ID for life and a revision number when it changes. And it had to cover both my work notes and processes, and my personal projects in one scheme.

The ID grammar is:

PREFIX-TYPE-SUBJECT.SEQ + revision

For example, CXO-PD-1000.1 is Customer eXperience Ops - Policy Directive - 1000 (the catergory of onboarding/team details) - 1 (document one). This would be for a document that is used for stating what is done and who owns it. It handles the rules of the task but not the actual routine of the task itself, that would go into a Procedual Requirement (PR) document.

There are two dialects of the same grammar:

  • Work: prefixed CXO, for my work functions. Things like process docs, reviews, data requirements, workflows, release notes, etc live here
  • Personal: keyed by a mission code instead of a department. Things such as a project and what its codes look like, notes on HomeAssistant, etc. Same rules, different prefix, so I only had to learn one system.

Letting a script do the boring part

Numbering schemes die when allocating the next number is a chore. So I wrote docreg.py, a small Python CLI with no dependencies outside the standard library. It:

  • allocates the next free ID so I never bump into another document that exists already
  • keeps a JSON registry of everything that exists
  • generates the markdown file for a new doc and rebuilds the index files

Does it fix the original problem?

Ultimately? It goes a long way into helping with the categorising and findind things part of the equastion. Before I would be searching through only to find that I had put a typo in a tag or that I used different wording in a phrase, this way everything is numbered and organised cleanly and quickly.

For example, I needed to locate a process that I had been working on for cucstomer churn, I knew I could locate that within the 5000 block of my documents, then under a subcategory of 53 and was the 3rd in squence. So I knew I could quickly go to CX0-PR-5053.3 and found the doc within a few seconds. If I had attempted to search via the steps I needed I would have had a dozen documents to find, having things categorised as such meant it was easy and fast to find.