A style guide for my personal knowledge management system (powered by org-roam):

General

Node types

Type Tag Description Example
Concept concept A single idea/concept Plans Within Plans
Reference reference The node-form of a specific citation Dune
Quote quote A single quote Plans within plans within plans
Person person About a single person Baron Vladimir Harkonnen
Poem poem A single poem Litany Against Fear

Tags

Prefer links to tags. Maintain the validity of the tags associated with node types.

Quotes

Attribution

  • Place attributions on the last line of the quote.
  • The attribution may, but doesn’t have to, be italicized.
  • The form of the attribution should be one of, in order of preference:
    1. Ideal: “<link to person>, <citation>”
    2. “<person>, <citation>”
    3. “<person>” or “<citation>”
    4. “<general link>”

Does it need attribution?

Every quote should contain an attribution unless it meets one of the following criteria:

  1. The quote is from a cited source which appears in the node’s bibliography and this source is the only citation present in the node.

Examples

I am increasingly convinced that the difference between effective and ineffective people is their skill at developing a theory of change.

Aaron Swartz, (Swartz 2010)

Muad’Dib learned rapidly because his first training was in how to learn. And the first lesson of all was the basic trust that he could learn. It’s shocking to find how many people do not believe they can learn, and how many more believe learning to be difficult. Muad’Dib knew that every experience carries its lesson.

Princess Irulan, (Herbert 1999)

Org is a mode for keeping notes, maintaining TODO lists, and project planning with a fast and effective plain-text markup language. It also is an authoring system with unique support for literate programming and reproducible research.

org-mode Manual: Summary

Large quotes are okay

There isn’t a hard rule on how much quoting is too much. Large quotes have their benefits.

Nodes can just be a quote

Quotes can live in stand-alone single nodes (eg: The First Lesson). This is multi-purpose:

  1. When in doubt, make the node smaller.
  2. Easier to link to specific quotes: Suppose a reader clicks on a link and arrives on a page with five quotes visible. This may confuse the reader. Which of the visible quotes is the right one?
  3. Future-proof: We will be able to, eventually, provide hover previews (similar to those used on gwern.net). Similarly, standalone quote nodes will fit into a transclusion model better than multi-quote nodes.

Favicons are nice additions to links. They provide visual context to where the reader expects the link to take them. Let’s include them alongside external links. I’ve written a script to make the process easier.

Backlinks are the backbone of a powerful zettelkasten system. The published form of these notes must include backlinks.

References

Herbert, Frank. 1999. Dune. London: Victor Gollancz.
Swartz, Aaron. 2010. “Theory of Change.” http://www.aaronsw.com/weblog/theoryofchange.

Links to this note