Portability
Your PKB should be a lifelong companion, evolving to fit your needs and helping you solve problems. You need to be able to trust that something you’ve put into your knowledgebase can be accessed 10 years from now. In order to accomplish this, you should own your data, and have it in a format that you understand.
What does portability mean?
File Format: I have a strong preference for plaintext over things like Word or Google Docs. In theory, you could export those docs if the software ever became unsupported, but you have very little control over the export result and its suitability for your needs.
File Content: I have a strong preference for native formats that directly represent my knowledge as data. For example, in
markdown, there is no “table of contents” directive, so there are two ways this can be accomplished:
A plugin in your editor could parse the headers and auto-generate a table of contents with lists and links:
example.md- [First Section](#first-section)- [Nested Section](#nested-section)# First Section## Nested Section
This is my generally preferred option, since any other markdown parser will understand this, and doesn't couple you to some special "table-of-contents" program, but rather expresses what you want with your table of contents as "data", directly in markdown.
You could make a dialect of markdown by adding a custom directive that your editor uses.
example.md![toc]# First Section## Nested Section
I dislike this option because other tools won't understand this special dialect, which makes this essentially "code".
Rendering: I enjoy interleaving some visuals and code in my knowledge, but I prefer native features like markdown’s typed codeblocks for including the code, and then having plugins for my renderer to handle specific codeblocks in certain ways (for example, understanding
mermaidand rendering charts, orlatexand rendering math). This way, you retain progressive enhancement: every markdown parser will display it as a codeblock at minimum.
