The format of a note

Last edited June 2021
Backlinks: Perpetual interests

I’m aiming for consistency in the way I write my notes. Their format is as follows:

Each note has a title. The title might describe a concept (such as the structure of a note), make a claim (such as Short-lived branches are indispensable for refactoring), or describe a process (such as Drive change by writing structured proposal documents).

Each note has content. The structure of the content is free-form (I have some longer-form articles on this site, and for those, the structure of the content matters more. ). I use Markdown, even though Lightweight markup languages are inadequate for technical writing, because that is what Bear, my note-taking app, uses.

Each note has a revision date, but not a publication date. Notes are intended to be ever-green and thus continuously updated, and an original publication date would therefore not be relevant. The revision date is relevant for readers, even if just to confirm that the content is indeed up to date.

The bottom of each note has a list of references (if there are any). It might make sense to split off references (resources I referred to in the note) from further reading (resources that elaborate on the note but are not referred to).

I might add something along the lines of Gwern’s confidence tags. I like the idea of making it clear how strongly I feel about certain topics: some of these notes are purely exploratory experiments and might fall apart as soon as I get some feedback, while others notes are well-established and reflect my long-term thinking.

I’m still figuring out the taxonomy. I like the idea of a hierarchy, but might mix it with tags. In any case, search works well enough for me now, and the amount of content does not warrant more organization.

The list of notes is sorted by title, because Short-form content doesn’t need to be written as a chronological sequence of blog posts.

I write my notes in Bear. I’m Importing notes from Bear into Nanoc. To do: This might be good to write up as a colophon.


“About This Website · Gwern.Net.” n.d. Accessed March 20, 2021.