Notes best practices
These best practices are created as a set of personal choices, based on previous experience (since last millennia, around 1994) with many tools and also how to better extract information from the data stored in my notes. I design things based on how I use them, not the other way around. With that I mean that the tools will adapt to me (most of the time) and not the reverse.
There are some particularities that apply to my use cases only, while many things can be broadly used with the same results or even as the basis for something better. If you happen to see these notes and have any suggestion for improvement, please share it with me.
This is not an exhaustive list nor a complete note: it will be expanded as and when things evolve in my eternal note-taking process. It has already evolved from various systems and is currently being updated to Obsidian terminology.
For basic Obsidian things, please check my other note: Obsidian - getting started.
Main takeouts
- Use standards whenever possible (YAML, JSON, CSV, WikiLinks, ISO-8601, ASCII, etc.).
- Use templates and automation to keep the overhead low.
- All important information and metadata must be part of the note, trusting OS metadata leads to wrong status and answers. (See Managing time and dates in notes / Managing time in notes)
- Design things for how they'll be used, not only for input.
- Backup is not sync, sync is not backup: they serve different purposes and should have different specific strategies.
- Keep add-ons / plugins to a minimum, using them only when the core functionalities do not address an existing real issue (and don't install them based on something that might happen someday).
- If it works for you, it doesn't matter what other people do: keep moving!
- It isn't because it works that there's no better way to do it: test and improve often. (See An example of vault evolution — Template change/ Vault evolution and changes)
- Functionality over appearance — but it can't be ugly.
- What you don't work with, you don't know (take care with Artificial Intelligence, large language models, Machine Learning and automations to generate things).
- The quality of your work while inputting and maintaining your notes is proportional to the quality of the output you get from them.
What about the 'second brain' concept?
This is more specific to Obsidian, as it is touted as a second brain. I don't see it as a second brain, but a note repository. A brain is able to autonomously identify new concepts and create new things and solutions. It can change and optimize relationships and contents.
Obsidian allows for improvement on a person's single brain by helping recover concepts, analyze relationships between them, identifying common topics, etc. but it does not produce any new output per se. Some plugins related to Machine Learning and Artificial Intelligence allow for some of that, but they are not Obsidian: they are services that are integrated into Obsidian via plugins. AI can be used for note processing with Obsidian, but the gains to the person itself aren't clear if everything is automated (I mean: you end up with a note repository, where some of these were created or manipulated by an AI, but you still will use it by searching what is in there).
Folders
flowchart TD
%% Estilos
classDef vault fill:#111827,stroke:#111827,color:#F9FAFB,font-weight:bold
classDef root fill:#1D4ED8,stroke:#1E3A8A,color:#EFF6FF,font-weight:bold
classDef lvl1 fill:#059669,stroke:#047857,color:#ECFDF5,font-weight:bold
classDef lvl2a fill:#F59E0B,stroke:#D97706,color:#FFFBEB,font-weight:bold
classDef lvl2b fill:#EC4899,stroke:#BE185D,color:#FDF2F8,font-weight:bold
classDef attach fill:#6B7280,stroke:#4B5563,color:#F3F4F6,font-weight:bold
%% Estrutura
A[Vault] --> B[Root - Inbox]
B --> C[1st level]
C --> D[2nd level]
C --> E[2nd level]
D --> D0[00attachments]
E --> E0[00attachments]
{init: {
'theme': 'base',
'themeVariables': {
'background': '#0F1520', 'primaryColor': '#253048', 'primaryTextColor': '#E8EAF0',
'primaryBorderColor': '#4A90D9', 'secondaryColor': '#2E3D5E', 'secondaryTextColor': '#E8EAF0',
'secondaryBorderColor': '#4CAF7D', 'tertiaryColor': '#1E2A44', 'tertiaryTextColor': '#E8EAF0',
'tertiaryBorderColor': '#C8A8F0', 'mainBkg': '#253048', 'nodeBorder': '#4A90D9',
'clusterBkg': '#253048', 'clusterBorder': '#4A90D9', 'titleColor': '#4A90D9',
'edgeLabelBackground': '#253048', 'lineColor': '#4A90D9', 'textColor': '#E8EAF0',
'noteBkgColor': '#2E3D5E', 'noteTextColor': '#E8EAF0', 'activationBkgColor': '#2E3D5E',
'activationBorderColor': '#4A90D9', 'actorBkg': '#253048', 'actorBorder': '#4A90D9',
'actorTextColor': '#E8EAF0', 'actorLineColor': '#4A90D9', 'signalColor': '#B0C4DE',
'signalTextColor': '#B0C4DE', 'labelBoxBkgColor': '#253048', 'labelBoxBorderColor': '#4A90D9',
'labelTextColor': '#E8EAF0', 'loopTextColor': '#B0C4DE', 'fillType0': '#1A2E40',
'fillType1': '#1A2A1E', 'fillType2': '#2A1E38', 'fillType3': '#1E2E3A', 'fillType4': '#2E2A1A',
'fillType5': '#1A2838', 'fillType6': '#2A1A2E', 'fillType7': '#1E3A2A', 'classText': '#E8EAF0',
'attributeBackgroundColorEven': '#253048', 'attributeBackgroundColorOdd': '#2E3D5E',
'pie1': '#4A90D9', 'pie2': '#4CAF7D', 'pie3': '#C8A8F0', 'pie4': '#F0A030',
'pie5': '#E05A5A', 'pie6': '#7AB8F5', 'pie7': '#6ACFA0', 'pie8': '#D4B8F8',
'pieTitleTextColor': '#4A90D9', 'pieSectionTextColor': '#E8EAF0', 'pieLegendTextColor': '#B0C4DE',
'fontFamily': 'Inter, sans-serif', 'fontSize': '14px'
},
'flowchart': {'nodeSpacing': 30, 'rankSpacing': 30},
'sequence': {'actorMargin': 50, 'messageMargin': 30},
'gantt': {'barHeight': 20, 'barGap': 4}
}}{init: {
'theme': 'base',
'themeVariables': {
'background': '#0F1520',
'primaryColor': '#253048',
'primaryTextColor': '#E8EAF0',
'primaryBorderColor': '#4A90D9',
'secondaryColor': '#2E3D5E',
'secondaryTextColor': '#E8EAF0',
'secondaryBorderColor': '#4CAF7D',
'tertiaryColor': '#1E2A44',
'tertiaryTextColor': '#E8EAF0',
'tertiaryBorderColor': '#C8A8F0',
'mainBkg': '#253048',
'nodeBorder': '#4A90D9',
'clusterBkg': '#253048',
'clusterBorder': '#4A90D9',
'titleColor': '#4A90D9',
'edgeLabelBackground': '#253048',
'lineColor': '#4A90D9',
'textColor': '#E8EAF0',
'noteBkgColor': '#2E3D5E',
'noteTextColor': '#E8EAF0',
'activationBkgColor': '#2E3D5E',
'activationBorderColor': '#4A90D9',
'actorBkg': '#253048',
'actorBorder': '#4A90D9',
'actorTextColor': '#E8EAF0',
'actorLineColor': '#4A90D9',
'signalColor': '#B0C4DE',
'signalTextColor': '#B0C4DE',
'labelBoxBkgColor': '#253048',
'labelBoxBorderColor': '#4A90D9',
'labelTextColor': '#E8EAF0',
'loopTextColor': '#B0C4DE',
'fillType0': '#1A2E40',
'fillType1': '#1A2A1E',
'fillType2': '#2A1E38',
'fillType3': '#1E2E3A',
'fillType4': '#2E2A1A',
'fillType5': '#1A2838',
'fillType6': '#2A1A2E',
'fillType7': '#1E3A2A',
'classText': '#E8EAF0',
'attributeBackgroundColorEven': '#253048',
'attributeBackgroundColorOdd': '#2E3D5E',
'pie1': '#4A90D9',
'pie2': '#4CAF7D',
'pie3': '#C8A8F0',
'pie4': '#F0A030',
'pie5': '#E05A5A',
'pie6': '#7AB8F5',
'pie7': '#6ACFA0',
'pie8': '#D4B8F8',
'pieTitleTextColor': '#4A90D9',
'pieSectionTextColor': '#E8EAF0',
'pieLegendTextColor': '#B0C4DE',
'fontFamily': 'Inter, sans-serif',
'fontSize': '14px'
},
'flowchart': {'nodeSpacing': 30, 'rankSpacing': 30},
'sequence': {'actorMargin': 50, 'messageMargin': 30},
'gantt': {'barHeight': 20, 'barGap': 4}
}} Decisões
Q1["Does it impact the whole note?"]
Q2["Does it impact / actuate at the body of the note?"]
Q3["Is it a field for a query to find the note?"]
Q4["Is it a field for a query for local body text?"]
Q5["Will it be used as a filter to list or not that note?"]
%% Destinos únicos
F["Frontmatter"]
B["Note body"]
%% Fluxo
Q1 -->|Yes| F
Q1 -->|No| Q2
Q2 -->|Yes| B
Q2 -->|No| Q3
Q3 -->|Yes| F
Q3 -->|No| Q4
Q4 -->|Yes| B
Q4 -->|No| Q5
Q5 -->|Yes| F
Q5 -->|No| BSimple example of decision process for where to add metadata information
Anything on the front matter refers to the whole note. If the information is valid for the note, it should be added there.
Anything on the body note refers to that specific part of the note.
Context dictates where things go.
This is valid for data fields, variables, block IDs, tags, etc.
On the tags issue, particularly, those are global per nature, but some plugins — such as Tasks and Dataview plugins — use tags to find items in lists or task lists.
Tracking contacts information
As a user of Android and Gmail for a long time, I have all my contacts sync'ed with Google Contacts.
For people, and some vendors, I have a contact with their full name and a note with the same name (full name), having a “Contact information” section at the note linking to the Google Contacts site. The same can be done from the contact site, with a link to the note with their name – but I didn't get to do it out of laziness. It can use the “obsidian://” URL targeting the note.
I've generalized this and created a Template - stakeholder template file. I’ve later refined this template and split it into two different templates: one for people and another for organizations.
I don't have a note for every contact. Some of them are only linked to a note that doesn't exist. If the need arises, then the note is created. As contacts are already linked, once these notes are created they will work for all existing links. For links that do not exist, the Backlinks core plugin helps to find these items.
Also, nicknames, abbreviations, etc. that are commonly used should be listed as aliases, allowing the recognition and automatic suggestion of those values as well.
Mathematics
When possible, never hesitate on using
If it is not possible and the system do not offer something usable (Equation editor, I still remember you!), then draw it with
Note length
A note should be as short or as long as it needs to be. There's no need to optimize early.
If a part of a note is required in multiple other notes, then refactoring can be done.
The exception to that rule is for items that are already known to be reused often, these should be created as separate notes right away.
If unsure, let it all in a single note until refactoring / reuse is required.
This has further evolved in Splitting Notes.
From here, you can end up with Atomic notes and Molecular notes.
Multiple languages
As a person who speaks, reads and talks more than one – or two – languages on a daily basis, I have notes in mixed languages. You might have already noticed that here.**
The easiest way to cope with that is writing the note in the language that suits it better – be it audience, usage, based on the language of the source, etc. Then, having multiple aliases covering all the languages where the note might be used will take care of linking even if the note is cited in a different language. Today, translation services can be automated, so there's no reason not to write in the language you want to.
For example: personal notes might not require a second language, as they are usually written in your mother tongue; but work related notes can be in multiple languages, and the same applies for notes to be shared with the Internet (such as this one).
The other alternative is using a single language for everything, but then be careful with automation sources and information generated by #Plugins (Obsidian), extensions, modules, add-ons, etc. as they might come in a different language, making the text out of place.
Note structure and contents evolution through time
Making changes when there are many (hundreds, thousands) of notes in your repository is always hard.
The more structural the change, the harder it gets. (Metadata, I'm looking at you! Header structure / depth, etc.)
Some note-taking applications allow you to make mass change to notes with the application itself, while others either don't allow mass change at all or allow it only through external tools.
Use what is better. Remember to backup first (#Backup vs Sync).
The important thing is: you will change with time and as you know the tool better, so don't fear changes. Think on how to implement them, try some kind of automation, take a deep breath and go for it. Sometimes you might want to process all notes at once. Sometimes you might want to make the change valid from that moment forward, ignoring old notes.
It will depend on what the tool allows, how you will use the new structure, and how willing you are with partial results until everything is migrated. If you have a kind of archive for old reports / automation, don't worry and use it. At last, you can also adapt the automation to work with both scenarios, in case you keep old notes without the upgrade or until the upgrade is complete.
Check Vault evolution and changes for an example.
Note relationship
I usually don't specify any special relationship between notes, but I'm willing to experiment improving how things are related to each other.
For that, my option of choice has been using a cardinal representation of these relations, as in the Idea compass. 
The cardinal representation comes from note properties with the names above, in lowercase: parents, children, similars, opposes.
The “previous” and “next” relationship is the currently obtained with links (next) and backlinks (previous). But, I also have them as part of my possible properties, just in case I need that reference somehow.
The exhibition of that relationship graphically is — here at my vault — performed via the Excalibrain plugin (GitHub - zsviczian/excalibrain: A graph view to navigate your Obsidian vault).
This kind of assessment makes analyzing notes relationships a bit more complicated, but this also might lead to more insights and a better understanding of the information with richer contexts and more complete ideas.
You can find a lot more of contexts at Semantic linking.
Backup vs Sync
There are two concepts that sometimes get misinterpreted. Note repository (or individual note) synchronization (sync) and backup.
The idea for a backup is taking a snapshot of the note or the note repository at a given moment in time. At the moment of the backup, the backed up objects must be in a healthy state, so that it can be recovered with little to no effort in case something goes wrong. It is also important to know that if the "backup" is on the same computer disk as the original files, then it is not a backup. The backup must live in a different media (an external SSD disk, for example).
On the other hand, the purpose of synchronization is to maintain two or more copies of the data equal. Replication can happen in one or two directions: 1) from the user to the repository; or 2) from the user to the repository and the repository to the user. The most common implementations available to users consider that replication can happen in both directions. This has been popularized with cloud solutions and the need to sync things between computers and mobile devices, where changes can happen in both devices.
There are peer-to-peer alternatives for replication that do not go through public clouds. One of them is syncthing, which connects authorized devices when they are available in the network and sync their data in both directions.
It is also possible that some solutions can work with both scenarios, and this is what usually happens with code versioning systems (CVS) such as git, Subversion, etc.
Considering portability and easy of setup, git with GitHub (now that personal repositories can be private and free) is a very common alternative to end users.
Backup routine
Nonetheless, even though git – for example – can make both roles, it is good to have offline backups or have them stored in a different cloud other than GitHub's.
A good backup schedule depends on how risk averse you are. The more averse to risk, the closer your backup windows must be. For non-critical data, a weekly or monthly schedule is fine. For critical data, you might want daily backups at least.
Sync
With Obsidian, my strategy for sync has moved to OneDrive. This allows me to benefit from some desirable side effects:
- OCR and indexing of images and PDFs.
- A simple version history for files.
- A 1 TB storage area for the vault and companion files (images, videos, audio, PDFs, Word, Excel, PowerPoint, etc.).
- Integration with Microsoft Copilot. (It is important to check for possible privacy issues here!)
Dashboards
I use dashboards as central consolidation panels. I have them for:
- birthdays and anniversaries.
- books read.
- recently changed and created notes.
- existing note categories and types.
- health tracking.
- inexistent notes and untitled notes.
- TOP 5: tags, categories, biggest files, referenced files (inlinks).
Every item above is a "module" and can be embedded to a note to show its results and create a "control center" or "visualization center" for everything.
Particularities
Books
Here I use the Minimal Themes cards view to present book covers and some data. Initially I only had what Kindle Highlights plugin provided. I've later expanded this to also allow for Book Search plugin results, where I planned both possibilities to generate a similar structure for the highlights.
Health
For health tracking, I use Obsidian Charts plugin. One thing that bothered me for a long time - until I was enlightened - was plotting the duration.
I had an issue with the Y-axis with the duration overflowing every 24h and restarting from midnight when the duration was longer than 24h.
I have solved this with the conversion of the duration time to decimal hours, with a function native to moment.js:
var fasting = pages3.map(p => Duration.fromISO(p.fasting).as('hours')).values
var cetosis = pages3.map(p => Duration.fromISO(p.cetosis).as('hours')).values
With that, Y-axis becomes a numeric axis and plotting any value becomes simple.
X-axis contains the date of the measurement.
Testing and Regression tests
These are simple use cases that can be thought of as a check on upgrades to see if anything fundamental to the daily workflow is broken or not.
It also serves as additional documentation for add-ons and features used in the note repository.
Make these simple, and then complex: a minimum of a simple implementation and a maximum of two or three implementations on the same note. It won't matter if there are 50 use cases in your repository if the simplest one stops working or if a critical complex implementation stops working.
The RegressionTests folders also serves as a playground for testing new add-ons without polluting the rest of the repository. This test will become part of the regression tests you'll have in case you decide on maintaining the add-on in your repository.
When implementing new contents and automations that change the notes themselves, one of the basic tests that can be performed is a simple search text on the new string as well as on the old string.
Final note: a Jack of all trades?
Is Obsidian – or any other tool and especially note-taking tools – the ultimate solution to all problems? Unfortunately no.
There are lots of specialized tools that perform much better than Obsidian.
What we should seek is:
- Reducing the number of tools for everyday tasks
- Using the best tools for what needs being done
- Trying to integrate all the tools we have
For example, it is easy to create a semi-CRM tool with a note-taking app such as Obsidian, but then other apps that use the contact information will lose their ability for that (WhatsApp, Telegram, Twitter, etc.).
The best option is linking to those tools so that when the link is clicked you get access to the information or duplicating the minimum possible information, while also keeping a link to the information at an app or website.
Related Notes
My repositories used to be a personal account on Evernote, a notebook at Microsoft OneNote, and the equivalent to these in other software programs. Even folders using tools such as Visual Studio Code and Emacs. ↩︎