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 plain language
- Use serial commas
- Vary the length of sentences
- Be useful
- Avoid qualifying language
- Be explicit
Use sentence case in headings and titles
Use “Sentence case”, rather than “Title Case” in headings and titles.
Node types
Type | Tag | Description | Example |
---|---|---|---|
Concept | concept | A single idea/concept/term | 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 |
Recipe | recipe | A cooking recipe | Cayla’s quarantine ramen |
Ingredient | ingredient | A cooking ingredient | Seitan |
Prefer links to tags
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:
- Ideal: “<link to person>, <citation>”
- “<citation>”
- “<link to person>”
- “<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 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:
- 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 one to which the link pointed?
- Works in a transclusion model better than larger nodes
Links
- Preserve links in the original quote to point to the original location or to a node representing the same idea.
- Wrap added links with square brackets just as you would with additional text.
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. Include them alongside external links. I’ve written a script to make the process easier (a).
Every node must include backlinks
Backlinks are the backbone of a powerful zettelkasten system. The published form of these notes must include backlinks.