Everyone says the most important thing in a team is “communication” but this is like saying the most important thing in football is “passing”. Passing is a necessary skill to be sure, but it’s only necessary because the wrong person has the ball. This happens to be most of the time because there is only one ball.

That only one ball exists is kind of the whole point of a sport but an organisation’s knowledge doesn’t need to have this limitation. Knowledge like specifications, decisions, passwords, complaints, approvals, bugs, concepts, notes, dreams, questions, feedback, etc can be digitised and shared without limit.

But organisations still toss information between each other right at the moment it’s needed and promptly discard it once it is used. This is a “just in time” attitude to knowledge. It would be fine in terms of teamwork if getting the knowledge “just in time” didn’t mean “bugging your teammates all the time”.

I co-founded Health Horizon with global ambitions in 2015 and we soon had a globally distributed team. This made communication problems painfully obvious because any reliance on passing information from one person to another could take an entire day or more!

I saw Roam’s structureless-but-easy-to-retrieve nature as a potential way to record all the information that must change hands in a way that builds up a cohesive, practical knowledge base and eliminates the need to manually exchange that information ever again.

So nine months ago I cancelled our subscriptions to Trello, Productboard, Pipedrive and a few others — and took the plunge with Roam. Here are some things I’ve learnt.

1. Dedicate a graph to it

One account (the “main” account) needs to dedicate one of their Roam databases to be the company database. Only paid subscriptions get their own database. Each team member can be invited to the graph and they can use it with a free account. When they sign in they can scroll down past the paid subscriptions options to access the graphs shared with them.

This means you can run a team graph with as many people as you need for $15/month. If you do it right, that’s a CRM, sprint management, documentation, specifications everything for $15/month. Astonishing value really. Even better a believer account gives you three databases for $500 for five years!

One of the aims of Roam Research is to have a world of interconnected graphs. The obvious approach would be to somehow link each team member’s private graphs along with official pages to form a company graph. This isn’t possible yet because so far you can’t merge graphs. I happen to be skeptical this will ever work, but you don’t need it so you shouldn’t split knowledge between your personal and organisational graph. You should just make a dedicated Roam graph for your organisation and move anything about your organisation from everyone’s personal graph into there.

2. Team Roams are “inside out” personal Roams

I wouldn’t recommend the usual approach of putting everything into your Daily Notes. This is the most common way to use Roam as an individual (it’s how I use it as an individual). This approach gives you meaty Daily Notes that act as a spine referencing disparate pages of your graph. These pages usually have little content but lots of references to Daily Notes and few references to other pages. It’s great for quick input and for making unforeseen creative connections after the fact. But in team graphs you have other priorities.

The number one priority for teamwork is whether someone else can utilise your knowledge without having to communicate with you. For this reason, most knowledge should be placed directly into pages. I call this approach “Context First” because you end up with big, informative pages with the linked references representing relationships between your business components and a few references to Daily Notes acting as a chronological record of activity.

Practically this means any time you are inclined to  add a page or tag to a block in Daily Notes, you should instead go to the page you would reference and write the note there. This isn’t nearly as burdensome as you might think because, when we’re working, we tend to be at the computer working in-context. You don’t need the quick-note mentality of a journal.

In the “Context First” approach, the Daily Notes end up mostly empty, but their backlinks become solid gold.

3. Use Daily Notes as OUTPUT

Going page-first frees up Daily Notes to be a record of what happened on a given date. When I look at the Daily Notes for Health Horizon here is what I see:

  • The Daily Notes content contains things about the day (eg Today is #@Mathew’s birthday) and maybe some notes that people couldn’t find a place for.
  • The Daily Note’s references is where the magic happens. When pages correctly represent the business context, a day’s linked references pulls in all the organisation’s activity for a given day. It shows the technical sprint tasks reported today, sales tasks due today, other tasks completed today, notes taken from phone calls with clients or between team members, etc.

Here is an extract of some of the references for 27th November.

It takes a long time to start to define the high-level order that makes this work but it’s a great feeling to be able to scan a Daily Note page for a review of the team’s activities and business progress. Once you have the structure down, this referencing is free — the user doesn’t need to do anything special to “report” what they’ve done.

4. EVERYTHING must be written down

In the introduction, I listed some of the things that constitute knowledge: specifications, decisions, passwords, complaints, approvals, bugs, concepts, notes, dreams, questions, feedback and more. The rule I use is that anything that may conceivably be needed again should be written down on a page. Everything.

If you’re not ready to move absolutely everything into Roam, here are the areas that benefited most from us moving them to Roam, in order:

  1. Technical documentation (specifying components, updating components, referencing places components are used)
  2. Call notes (building call agendas, making notes during calls, keeping track of where ideas came from)
  3. Sales CRM (people, organisations, call agendas, follow up todos)
  4. Product management (feature requests)
  5. Service delivery (tasks, feedback, client communications)

You’ll never forget the moments where you think “Oh well, have to write this email, I better document it as I do” just to find it already documented for you, ready to copy and paste. It’s a wonderful feeling. This is very time consuming in the early days but it gets easier over time. You get better at it but also you only have to write things once.

5. Everything should be written down ONLY ONCE

When everything is written down, you run into the issue of duplicate notes. These aren’t a problem in and of themselves but duplicate notes mean you lose the source of truth. Luckily Roam is built for just this. If the same thing needs to be said on two pages, there are two options:

  1. Decide which page is its true context, write it there and reference it with a block reference on other pages
  2. If it truly doesn’t have a home in either, write it in one page and embed the block in the other. This is very rare. I think we have 3 embedded blocks in our entire database.

This is especially true for technical documentation because Individual pages can represent components in code and blocks can represent data or specifications. For example, we have multiple user subscriptions at Health Horizon with different limits on what they can do. A paying user can follow the development of 60 technologies while a free user can only follow three.

The code obviously needs to be aware of these limits but so too does the landing page and so too does the marketing material and sales people. By having a block “professional follow limit is 60” on the [[User Limits]] page, we can reference this block on the landing page and the marketing specifications and sales pages.

If we decide to change this limit later on the User Limits page, then the landing page, marketing and sales pages will always show the updated number. Block references require discipline. It is a task in and of itself to break down components and ideas in just the right way to atomise specifications into a block.

You can also view all the references to the block to see everywhere it is used. This has helped me understand the implications of a change across the entire business. It is also useful to work out who you should notify of any given change.

6. Use notifications and tags sparingly

As I understand it, notifications are part of Roam Research’s roadmap for multiplayer Roams but many teams have hacked their own solution. Ours uses #[[@name]] to refer to a person and #[[@name]]  to refer and notify the person. Whatever system you use, keep it simple.

The tags with speech bubbles are pulled into a users’ own personal page via a query. Once a user wants to clear the notification, they delete the speech bubble and it reverts to a normal mention.

We use global CSS to warn the user they’re notifying someone (red outline) but the real trick is to install a bit of custom CSS into each person’s browser to get the notifications for you only to pop (red outline and red fill). This is not the only time CSS has made our life easier.

7. Spend time on CSS

Roam isn’t pretty but you can make it pretty. I started by setting the fonts and link colours to match the theme of our website and gradually tweaked it from there. I had no experience in CSS so don’t let an unfamiliarity with CSS scare you away.

Here is a real screenshot of our current Roam set up. The search bar is bigger and centralised. The right sidebar was modified to look as much like the main page as possible. Some content on the left sidebar has been hidden. The pages in this example show two features in the process of being specced for a future sprint.


I find it very useful to define separate CSS for tags, especially to differentiate tags from pages when they’re referenced. These tags were hacked together using some CSS borrowed from Roamcult themes. I added a filter icon to some to indicate to the user it can be useful to filter these blocks out.

8. Learn to live with chaos

You cannot build a controlled, consistent project management platform in Roam and you shouldn’t try. Nothing can be enforced so you’ll have todos without dates, conversations in the middle of specifications and brain farts on orphaned pages. It’s OK.

It’s better than OK you should embrace it. It is very nice to break your structure on the fly. Ever wanted to comment on a particular Trello checklist item? Sorry, nope you have to comment on the card then explain “On checklist 3 task 3 you say ….”. But in Roam just throw a block wherever you need it and notify someone. It can be hard to get used to this freedom.

Every few weeks I find myself spending a day re-structuring some pages or changing how tags work. This process is surprisingly fun. Firstly, it’s easy. Roam’s back links mean you can easily change page titles and protect references even during harsh re-structures.

The main reason it’s fun though is because it gets you thinking at a high-level about your organisation. You can actively discern its component parts and their interactions free of a hierarchy, while you produce a valuable resource for the team.

9. I’m not going back any time soon

The team was frustrated in the early days and they almost never forgave me for the teething problems. But I see the holy grail so clearly and they are starting to see it too. Most of the pain was a result of moving to Roam after building up all our software and processes. It meant we had to build up a massive amount of documentation from scratch. It’s possible but painful. Starting a business with a Roam database would be much easier because you start from zero. I’m looking forward to the next business so I can start a team Roam from scratch.

I am nervous about moving to a larger team because it is easy to imagine how having more people making more changes would make it more difficult to maintain order and extract crucial information.

On the other hand, it’s feasible that the increased need for knowledge that comes with having more people would amplify the need for Roam and it may reach a point where it self-organises. There’s one thing I look forward to: we may just have the world’s best employee onboarding systems in terms of getting them up to speed with organisational knowledge.

I expect that, for a larger team, you would need a person with responsibility over the fidelity of the knowledge graph. In fact, if I’m honest, I spend a lot of time doing this right now. This could easily become a full-time job but I do see a world where this is worthwhile.

Most organisations leak knowledge like a sieve and waste an ungodly amount of money in lost knowledge, poor communication and not learning from past mistakes. Surely it’s worth having even multiple employees working full time to solve that problem? Perhaps Roam will see Chief Knowledge Officers make a comeback.

Should you move your team to Roam? Roam vs dedicated platforms

If you want to use Roam for teamwork, you need to accept you will never have a rock-solid defined workflow and that managing the system will take ongoing effort.

Online dedicated collaboration platforms free you from chaos but remember it’s a tainted deal. They will guarantee a certain minimum level of organisation and communication if you cram your team into their workflow. This is sold as an obvious advantage: your team doesn’t have a nice workflow and Asana will give you one. But I’ve always questioned this proposition.

If Evernote is a filing cabinet where everything must have a place, then Asana is a boot camp where everyone must follow a method.

Compared to this, Roam is a workshop. It’s messy but there are natural conflagrations of order where humans come together to produce. Where would you rather do creative work? There will always be wood shavings on the ground, chits on the wall and stained coffee cups on desks.  But everything the team needs is there and everything the team builds is there.

And whenever you take a moment to stand hands on hips to take in the soothing din of human productivity, you know that what you have and what you do in that space is unmistakably yours.

Note: This article has been updated since original publication to reflect graph access does not require a subscription.