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

Prose

I try to write with an emphasis on clear communication.

Use sentence case in headings and titles

Use “Sentence case”, rather than “Title Case” in headings and titles.

Node types

TypeTagDescriptionExample
ConceptconceptA single idea/concept/termPlans Within Plans
ReferencereferenceThe node-form of a specific citationDune
QuotequoteA single quotePlans within plans within plans
PersonpersonAbout a single personBaron Vladimir Harkonnen
PoempoemA single poemLitany Against Fear
ReciperecipeA cooking recipeCayla’s quarantine ramen
IngredientingredientA cooking ingredientSeitan

See Andy Matuschak | Prefer Associative Ontologies to Hierarchical Taxonomies.

Tags identify the Node type – not its content.

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. “<citation>”
    3. “<link to person>”
    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 (a)

Large quotes are okay

There isn’t a hard rule on how much quoting is too much. Large quotes have their benefits and are simple to capture using bookmarklets (Porter 2022).

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 one to which the link pointed?
  3. Works in a transclusion model better than larger nodes
  1. Preserve links in the original quote to point to the original location or to a node representing the same idea.
  2. Wrap added links with square brackets just as you would with additional text.

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

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

Bibliography

Herbert, Frank. 1999. Dune. London: Victor Gollancz.
Porter, Adam. 2022. “Org-Protocol-Capture-Html.” https://github.com/alphapapa/org-protocol-capture-html.
Swartz, Aaron. 2010. “Theory of Change.” http://www.aaronsw.com/weblog/theoryofchange.