Skip to main content

Organizing Your Notes in Roam - Understanding Pages, Blocks, Tags, and Outlining

Taking notes is very simple. You take a piece of paper and jot down a few thoughts. That's it.

But if it is this simple, why all the fuss? What makes quality note-taking so difficult?

A real-life note-taking situation

Here’s a real-life situation. I am on the phone talking to someone and the other person says something I need to remember. Since I have nothing else at hand, I quickly grab an envelope or a piece of paper, maybe a printed presentation slide, or some other document lying around on my table, and scribble few words on its back or on the margin where there is still some space.

So far, so good. I have created a “fleeting note”. I have captured the information. I ensured that the thought/action will not sink into oblivion. Once the call is over, I can recall the thought by looking at my note on the paper.

As the conversation continues, however, the back of the envelope has now become my notepad. I scribble other thoughts on it as well. Not just notes from the conversation, but as my mind processes the ideas I have written on the sheet, I embellish them with details, such as a quick impromptu root cause analysis, or the beginnings of an action plan. This process triggers other, more distant thoughts and ideas. I add them as well. As I run out of space, I rotate the paper to squeeze in a few additional words on the side, then turn it over, as there is further space there. Because the page/envelope is becoming crowded with words, to help trace back my thoughts, I add arrows, numbers, boxes, underlines, asterisks, etc.

Sometimes I don’t have time to process my notes right after the meeting and they end up in my bag or drawer. I am afraid to throw them out, fearing I will dispose of an important action or thought. Yet, if I would be honest with myself, the moment I added the second or third thought on the sheet, I have already lost my ability to manage that information efficiently.

When I pick these notes up later, typically when cleaning my bag or drawers weeks after the event, the clean-up extends to hours as I try to piece things together, working my way through long-forgotten notes.

It gets difficult with size

What makes note-taking and especially finding information difficult is the volume of notes.

Because of COVID-19, nowadays most of my meetings are virtual. This makes it slightly easier to capture notes directly into Roam, since I can type while on Teams/Zoom calls. This, however, does not solve finding information.

Having a single note (e.g. a phone number on a Post-it) is easy to handle. Having ten-twenty thoughts distributed over a few pages is more difficult. I currently have 24249 blocks of text in my Roam database, distributed over 3245 pages, with 16102 links such as tags, attributes, page links, and block references in between these.

To ensure your note-taking is scalable, you need to structure your notes for findability. Luckily, Roam offers several ways to organize your thoughts.

Pages

The Daily Notes page is central to Roam. When you open your database, each day an empty page awaits you. If there is a thought you want to jot down, and you don't quite know where to place it, you can simply write it there. Later, you can find this information by going back to the page for the day.

In my experience, time-based hierarchies are one of the best for finding information. I often use this for my file/folder structures as well. Most people have a good hunch when something happened and find information relatively fast by flipping the pages of their diary. Using the Daily Notes page alone will improve the findability of information greatly. But Roam offers much more.

Daily Notes Page

Beyond Daily Notes, the most basic way to structure your information is to create individual pages for topics and to write your thoughts there. Pages can include people, places, projects, books, articles, events, experiments, experiences,... anything.

In thinking about the use of Daily Notes versus dedicated pages, I find Mat McGann's distinction between "Context First" and "Daily Note First" organization of your graph very helpful. Nine things I've learnt from running my distributed startup in a multiplayer Roam | RoamBrain.com

Daily Notes First vs. Context First

In the Daily Note First approach (left-hand side on the picture), you use the Daily Notes page to originate your ideas. If there is a book you are reading, you make a note of that book on the daily notes page either as a page reference i.e. [[Title of the Book]] or simply tagging the block with something like #reading, or both. Referencing Mat’s picture. This is how the red and blue dots and links get created around the backbone of your Daily Notes.

Interstitial journaling is one way to keep track of ideas on the Daily Notes page. As an example, see my journal from yesterday morning.

Interstitial Journaling

In the Context First approach (right-hand side on Mat's diagram), you predominantly capture ideas on dedicated pages and create the context in your graph by linking these pages together. You can still capture chronology by including few references to the Daily Notes page. Examples of this approach in my case are the Minutes of Meeting pages. I keep my agenda on Daily Notes but capture the discussion and actions on separate pages dedicated to each meeting.

Blocks and outlines

By default, Roam displays each paragraph of text as a bullet point, also known as a “block”. Each block should ideally hold a single thought. This will not only help in reading of your notes but also maximize the reusability of your writing.

Roam is an outliner. You can organize your blocks into an outline using indentation (TAB and Shift+TAB). This approach helps to create context in your notes. The outline may go several levels deep. Each level receiving further context based on its parent blocks. I often end up with five or six-level hierarchies, sometimes even deeper.

Block Nesting Example

Information nested under a block are details that belong to that block (i.e. date > topic > meeting note/action). You could also write these in a single block connecting each piece of information with the word AND e.g. (we met on 4 January AND discussed Project 3 AND agreed on the following action). Breaking your notes down into an outline creates more granularity in your database; improving not only readability but also reusability and findability. Imagine for example that we discuss multiple projects on 4 January and agree multiple actions. Adding all these into a single block would make that block very hard to read and reuse.

Side note: How do I reuse the #discussWith action block? The next time I meet with [[Muck the Dumb Truck]] I will reference this action block in my meeting minutes, and nest the blocks summarizing the outcome of our discussion under it similar to the example below. (I took the examples from Minutes of Meeting pages)

Block reference

I borrowed the following two diagrams from Rob Haisfield's and Dhrumil Shah's Learning through Doing - Desigining for Feedback Loops to make References Paths Legible and Intuitive. They show how block outlines impact query results - i.e. findability.

The first example shows, how querying for [[Kitchen]] and [[Sink]] will return blocks 2a. + 2a1. and 1a., but not 3a. or 3b. This is because 3a. and 3b. are siblings and siblings are in a logical OR relationship. References in the same block and references nested under one another are in a logical AND relationship.

Query Example

The second example shows how the page on the left-hand side would look depending on the page filter applied.

  • If you filter the page for [[ex-E]], Roam will include its parent blocks, but will exclude sibling blocks - other child blocks of those parents.
  • If you filter the page for [[ex-C]], Roam will exclude its sibling blocks, but will include all of its children.

A block can have multiple children but only 1 parent. You cannot use a block's siblings to locate it with a {{query}} or filter. There are other advanced ways to locate blocks based on siblings, but these I will cover in later posts.

This concept might not feel intuitive at first, yet, it is super important to grasp this idea since this is at the heart of finding information in your graph. The best way to learn and internalize the concept is by creating test examples for yourself and playing with the query results and page filters.

Page filter logic

Side note: If you are wondering about page filters, you can access them by clicking the funnel icon next to search.

Page filter

Tags, Page Links, and Attributes

Once you have mastered pages and block outlines, turn your attention to #tags, [[page links]], and attributes::.

The difference between tags, page links, and attributes is mostly stylistic. In the background, Roam represent’s all of these as pages. i.e. if you create the tag #reading, then in the background Roam will automatically create a page [[reading]]. If you open that page, then under linked references you will see all the blocks which you have tagged with #reading.

The same is true for attributes. Attributes are also pages. However, with attributes, you can also build attribute tables. Diving into {{attr-table}} is beyond to scope of today's post. If you are interested to learn more, I recommend watching How to build a habit tracker in Roam (3 different ways). As a teaser, here's the code I use to create an attribute table for my daily habit tracker: {{attr-table: [[Number of meetings]] [[Start work]]}}

Because tags, page links, and attributes are essentially the same thing, this also means that in queries or filters you can use them interchangeably. They will all behave the same way.

One additional way many people use tags is to apply custom CSS formatting to them (e.g. see my #blog/draft tag in the picture above. You can find my css for my blog tag here: Keeping Your Notes Tidy - How do You Manage the Growing Number of Tags?).

Roam also offers a special type of tag for formatting blocks. These tags begin with a dot (e.g. #.red or #.ALLCAPS). Conor recently shared some examples of using these tags. You can find the link to his Loom demonstration video here

Closing thoughts

I am just scratching the surface in this post. Roam offers lots of tools to organize your notes for findability. It is however important to master the basics and to keep your system as simple as possible.

I recommend regularly reviewing your note-taking habits, looking for ways to achieve the same outcome but using simpler approaches. Spending the time to simplify things in the long haul will pay serious dividends when you are re-thinking how you want to organize your information, or when you are searching for stuff in your graph.

Let me close with a quote from Rich Hickey, the creator of Clojure. Based on Conor’s comments, the thinking patterns underlying Clojure and Datomic have had a fundamental impact on Roam’s design. While Rich was talking about software development in his speech, I think his statement equally applies to note-taking. With all the buzz in #roamcult, there is a huge temptation to install the latest {{roam/js}} script or component to your graph. While these can be nice, good note-taking does not require any of these. All it requires is the consistent application of simple tools like Daily Notes, content pages, tags, attributes, and most importantly outlining.

Happy note-taking!

Simplicity is a choice. It is not something that will ever fall out of tooling, practice, or anything else. You really need to do this work. This is the most important work that we do because doing this work makes everything else we do substantially and deeply easier.
Rich Hickey Simplicity Matters
Like this post?
Show your support.

Comments

Popular posts from this blog

Deep Dive Into Roam's Data Structure - Why Roam is Much More Than a Note Taking App

Which are the longest paragraphs in your graph? Which pages did you edit or create last week? How many paragraphs of text do you have in your database in total? Which pages do you have under a given namesapece (e.g. meetings/)?

Showcasing Excalidraw

Conor ( @Conaw ) pointed me to Excalidraw last week, and I was blown away by the tool and especially about the opportunities it opens up for  Roam Research ! It is a full-featured, embeddable sketching component ready for web integration. This post will showcase key Excalidraw features and discusses some of the issues I still need to solve to complete its integration into Roam. I spent most of my free time during the week integrating Excalidraw into Roam. This article will introduce Excalidraw by showcasing its features.

My GTD - How I Organize Meetings and TODOs in Roam

How efficient is your workflow for keeping on top of all your meeting notes, action items, contacts, projects and more?  If you were to bump into someone unexpectedly would you be able to remind yourself of all the relevant topics you wanted to discuss with the person?  Can you remember all the things you wanted to get done when running your errands?  Can you keep track of your discussions with all the people you talk to regularly? In this post I will walk you through my meetings-actions-people workflow in Roam. If you are new to Roam and Roam42... Just in case you are not familiar with Roam , it is an ultra flexible note taking tool. It's like the Excel for text. If you want to find out more, there is tremendous amount of quality content available on YouTube, just search from "Roam Research". Equally, you can head over to RoamBrain.com for all the best links and more. My workf

Roam-Excalidraw Plugin MVP Release

  I am releasing the MVP version of the Roam-Excalidraw Plugin. Over the past two weeks, I have been super focused on getting to this point. As a consequence, this post is going to be shorter and more utilitarian than usual. I had to make a choice whether to release the plugin this weekend or to write a detailed blog post. I opted for the first.

contact: info@zsolt.blog