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:
- Ideal: “<link to person>, <citation>”
- “<person>, <citation>”
- “<person>” or “<citation>”
- “<general link>”
Does it need attribution?
Every quote should contain an attribution unless it meets one of the following criteria:
- 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.
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.
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:
- When in doubt, make the node smaller.
- 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?
- 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.
Links
Show favicons alongside links
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.
Every node must include backlinks
Backlinks are the backbone of a powerful zettelkasten system. The published form of these notes must include backlinks.