Addicted to Block ReferencesMS Office vs. Roam vs. Obsidian

Setting the stage

I am leading a project to review my company’s business strategy. I want to identify projects for next year’s business plan and to create a strong link between the strategy and our projects. This will help in storytelling with the people delivering these projects and to the executives governing the strategy.

This exercise has put the gap between information and knowledge management tools I use in private and available at work in the spotlight. There are four capabilities I miss most at work: backlinks, block references, tags, and a query language to work with the information.

This post is about how I managed the process using standard office tools like Word, SharePoint, PowerPoint, and Excel, and how I could have incorporated Roam or Obsidian into this workflow were those available at work.

Spoiler alert! I have not found the silver bullet. While there is room for better linking and referencing in MS Office products, Roam or Obsidian wouldn't solve the challenge without supporting tools either. There are many trade-offs to consider. I need an ecosystem of tools to implement an efficient solution. In addition, there is no way around the hard work of reading, understanding and analyzing the strategy, and translating ideas into projects. Maybe a time will come when artificial intelligence can do this for us, but for now, this is a strenuous task that requires careful thought and a well-thought-through process.

Business context

I am heading up IT for our downstream business (refining, logistics and marketing). It is my role to translate the business strategy into an IT narrative. I must make sure that those who are delivering resulting IT projects and services understand how the pieces of the puzzle fit and how their work impacts others. I want to tell a story that starts with the business objectives and ends with concrete implications for our IT systems, services, technical skills, supplier contracts, etc.

We operate hundreds of applications and thousands of interfaces. We serve complex internal workflows and many customer and legal requirements. Applications, data, and infrastructure are grouped based on business outcomes. We call these groups IT Capability Groups.

There are over thirty Capability Groups for downstream. Routing and Scheduling, for example, supports the planning and execution of road transportation in 12 countries, including scheduling and dispatching, on-truck computers, and order generation for customers on our vendor-managed inventory (VMI) service, etc. Another example, the Customer Experience Capability Group, includes all our customer-facing tools such as e-commerce, customer relationship management, contract generation, e-invoicing, electronic data exchange, and more. Other examples are Environmental Management, Process and Fire Safety, Project Management, and Maintenance.

IT roadmaps define the work we need to succeed in the coming years. We use IT Capability Groups, to organize our IT roadmaps.

From strategy to IT business plan

Here's the high-level process we have designed to work our way through the analysis.

We first went over the strategy white paper with a marker to highlight each part that referenced anything digital. Our goal was to identify all the areas where IT could support the business strategy and to understand the impact of that strategy on IT. We then mapped these topics to the IT Capability Groups to assess the impact on IT roadmaps. Finally, all this analysis will land in the work plan for 2022 that will get translated into the business plan.

Capability Groups are not standalone entities. They are highly interdependent. Just think of the relationship between customer experience, routing and scheduling, and production planning. Customer orders will trigger deliveries, we send invoices after successful deliveries; the refinery produces products in line with customer demand forecasts, and even the best delivery schedule breaks if there is not enough inventory to meet all the customer orders.

This sequence of mappings ensures the traceability of requirements. It also provides the story to help IT operations and project teams understand how their work fits the bigger picture, to help with onboarding, and with identifying dependencies, integration points, risks, and opportunities. We also need the same mapping to track project and operational costs during budget planning and execution.

Backlinks, Tags, Block References, and query

I'd like to clarify a few concepts, before diving into the solutions.

Forward links

Forward links are references in a text that point to other documents. In Markdown we represent these links with double brackets. A forward link to the Routing and Scheduling Capability Group would take the form of [[Routing and Scheduling]]. Forward links are very common. You use them every day as you browse the internet. They are the links on a webpage that takes you to other pages.

Backlinks

Backlinks are the references that other pages make as viewed from "this" document. They are like citations. Backlinks are becoming increasingly common in knowledge and information management tools. They provide powerful ways to navigate a corpus of documents and to understand the broader context of a note. For example, backlinks could list all the locations in the white paper referencing a given IT project, service, or Capability Group.

Tags

Tags are categories. In Roam and Obsidian tags start with a hash (or number) sign, e.g. #project. You may organize tags into namespaces using the slash character, e.g. #Commerce/CustomerExperience or #Logistics/RoutingAndScheduling. In Roam tags are just a stylistic choice, under the hood, they behave exactly the same as page links. In Obsidian, tags behave differently. The built-in tag-pane plugin displays tags in a tree-hierarchy following the namespace structure and shows the number of references to each tag within the vault (i.e. the corpus of documents handled by Obsidian).

Block references

Block references take linking and referencing between documents to a whole new level. Blocks are another name for paragraphs in a document. They represent the unit of thought. In tools like Roam, Logseq, or Obsidian, using block references you can transclude a block of text into another document, thus citing a thought verbatim from another document and maintaining the link to the original text. Roam takes blocks and block references a step further by adding versions to blocks, i.e. you can maintain links to earlier versions of the text as your document evolves.

Block References in Obsidian

You can create a reference to a block by typing [[^^ continued with part of the text from the block you want to reference. A search window will pop up helping you select the block you want to reference. Once created, a block reference will look like this: 

Obsidian adds the reference ^fa2cae to the end of the referenced paragraph. The exclamation mark (!) in front of the brackets on the left tells Obsidian that the text should be transcluded, i.e. when you change from edit to preview mode, Obsidian will replace the block reference with the text from the source block. 

If there are multiple references to a block across multiple documents, the search can quickly display all those references. 

Block References in Roam

In Roam, every block has a block-id by default. In fact, under the hood, Roam stores documents as graphs, blocks being the nodes of the graph. Roam stores blocks and their relationships. Block references and the page on which your block "resides" are just different relationships involving the block. You can easily create a reference to a block by typing (( continued with text from the block you want to reference. Similarly to Obsidian, a search will pop up and you can select the block you want to reference. Another way to create a block reference in Roam is to right-click any block and to select "Copy block ref" and paste the reference to any other block within the graph. A block reference will look like this: 

The number in the top right corner shows the number of times you have referred to the block. On the left, you can see the reference to the block. Each block in Roam has a nine-character-long unique identifier.

The next screenshot demonstrates two features. First, on the left, it shows how the block reference looks as it is transcluded into the page. Second, by clicking on the number in the top right, Roam will show all the references to the block. You will find these references nested under the block. 

Document query

Roam offers two ways for querying documents. You can use the {{query}} command to find relevant blocks in your graph filtering on a combination of page links and tags. I explain the basics in this post: Organizing Your Notes in Roam - Understanding Pages, Blocks, Tags, and Outlining For power users Roam offers full access to its data structure using the query API. You can query the underlying Datomic database using Datascript. I have an in-depth article about Datomic and Datascript which you can find here: Deep Dive Into Roam's Data Structure - Why Roam is Much More Than a Note-Taking App 

Obsidian has a powerful search tool you can also embed into documents. Obsidian help provides a good explanation here: Search - Obsidian Help. If the built-in search is not sufficient for your purposes, you may install the Dataview plugin from community plugins. Using dataview you can build complex queries and customize how the result is displayed (as lists, tables, and by using additional plugins even simple charts). With dataview you can also tap into the YAML front matter of Markdown documents. Though it would be a very rudimentary solution, the front matter could be used to store structured information about projects such as budget estimates, estimated start and end dates, and more. 

Solution alternatives

I don't have Roam or Obsidian available at work. Obsidian's architecture is better suited for enterprise use, though even Obsidian would probably run into challenges with ring-fencing corporate information. Features such as community plugins would likely not pass the scrutiny of corporate information security. Roam as of now unfortunately simply does not stand a chance in its current state.

The actual solution

After evaluating our options, my team opted for Excel to capture the mapping between the white paper and the IT Capability Groups. Luckily, the white paper is well structured, with over seventy chapters, sections, and sub-sections. This provides reasonable granularity for the mapping, even though it is not at the paragraph/block level. The Excel sheet lists IT relevant topics identified while reading the white paper with a reference to the chapter where this topic is mentioned, plus mapping to IT Capability Groups and some commentary by the expert. 

An alternative solution that we have tried but rejected was adding comments and hashtags into the strategy white-paper in MS Word using an agreed set of tags representing the names of IT Capability Groups. While this solution offered a more immersive reading experience, unfortunately, there is no straightforward way to enforce a set of tags. Once ready, we could search comments and tags, but any in-depth analysis of the data would require complex Visual Basic macros. Also linking to other documents is possible via hyperlinks, yet this is very cumbersome and not effective when dealing with a high number of connections. Block-level referencing and backlinks simply do not exist. 

Once we are ready with the initial mapping, we create one-pager executive summaries for each Capability Group, recapping the business direction and highlighting the required technology investments. We capture these one-pagers in a SharePoint Form. We use Sharepoint in the next step of the process for managing the project proposal workflow and for storing all the project documentation for each identified initiative. Having the IT Capability Group group references in the project proposals on Sharepoint offers an indirect way to link the demand with the strategic direction stated in the white paper.

The final investment plan will end up in SAP, and the link between the project documentation in Sharepoint and the budget in SAP will be the SAP WBS code which is also captured in Sharepoint on the project proposal Form. While the links between the white paper, the excel sheet, the one-pagers, the project proposals, and the investment plan are not "hard references", this approach provides a good enough linking of projects back to the strategy.

How would my workflow change if I could use Roam or Obsidian

Translating the strategy into an investment plan is a complex process. Some data is "story" based and inherently unstructured, while some, like the budget information in SAP and the project proposal workflow, are transactional. While it would be possible to include budget and schedule information in documents (e.g. YAML Front Matter in Obsidian, or attributes in Roam), and it would also be possible to implement a workflow using Roam and Obsidian, these would be unsustainable hacks with lots of friction. I don't think that there is a one size fits all solution. Where Roam or Obsidian would shine is in the mapping from the white paper all the way to the project documentation.

One additional challenge that would need to be addressed is collaborative work versus personal knowledge management (PKM). My private PKM workflows and tools are, as the name suggests, personal. Analyzing a document alone is very different compared to analyzing in collaboration with others. The collaborative effort requires upfront agreements about ways of working, processes, value sets for tags, naming conventions, and some level of access management, to mitigate unintended damage by deleting, overwriting, etc. other's work.

How would I do this in Roam?

Roam has a clear advantage over Obsidian in multiplayer functionality. Roam has successfully hosted multiplayer graphs of over 2000 participants, in which everyone was collaboratively commenting and analyzing the same body of text during the various Roam Book Club events.

The would be process:

• I would load the white paper into Roam. For sake of performance and user experience, I would split the white paper by section and load all sections as separate pages into the graph.
• As I read the white paper I would add my comments, including links to [[proposed projects]] nested under relevant paragraphs in the white paper. I would also use the highlighter to mark key sentences in the white paper. I would also establish a set of tags to categorize my comments: e.g. questions, dependencies, prerequisites, opportunities, risks, etc. 

• I would create a project template that would include attributes for schedule, high-level budget data, and Capability Group. By nesting projects under relevant paragraphs of the white paper, Roam will automatically show all these backlinks with context on each project page. In a multiplayer setup Roam also records the name of the person creating each comment, thus it would be easy to identify the owner for each nested item should anyone need some clarifications. 

• Similar to project pages, I would also create a template for IT Capability Groups. Those would work very similarly to the logic of the project pages. Each Capability Group would automatically list all the related projects as backlinks.
• I would use an attribute table to create an overview of all the identified projects. 

• Going a step further, I would follow a similar logic for scoping each project. I would link these details to the project. Such linking would ensure that anyone interested in background information could easily traverse through the links to find the definition and roadmap of the related IT Capability Group and the business objectives stated in the white paper.
• It is possible to capture the SAP WBS code as an attribute on the project page, and with some coding a {{roam/js}} script could fetch basic SAP budget data, which I would link to the project by making the WBS/IM Position codes page-links, e.g. [[JBVNANP1]] and importing the data from SAP to the relevant page for the WBS/IM position.
• Finally, Roam could also auto-generate a visual representation of the Capability Group roadmaps using {{mermaid}} diagrams. For this I would write a simple {{roam/js}} script to run a datascript query that collects project milestones from projects linked to each Capability Group and creates a block with the relevant mermaid markup. My guesstimate is that I could achieve an MVP of this with less than an hour of work.

If you are interested in how I would push the solution check out my two posts on Roam Agile: Agile Product Management in Roam - Part 1 and Agile Product Management in Roam - Part 2. In these articles I show how Roam could host a fully agile development process, providing complete transparency from idea to implementation, through sprint planning, daily stand-up meetings, backlog grooming, and even customer feedback management.

How would I do this in Obsidian?

Obsidian is a personal knowledge management tool. That said, coupled with GitHub it is possible to implement a managed (though likely not seamless) multiplayer experience.

The would be process:

In many respects, the process would be very similar to that described for Roam above.

• I would load the white paper into Obsidian. For sake of performance and user experience, I would split the white paper by section and load all sections as separate pages into the vault.
• Just as in Roam, as I read the white paper I would add my comments, including links to [[proposed projects]] nested under relevant paragraphs in the white paper. I would also use the highlighter to mark key sentences in the white paper. I would also establish a set of tags to categorize my comments: e.g. questions, dependencies, prerequisites, opportunities, risks, etc. 

• I would create a project template that would include attributes for schedule, high-level budget data, and Capability Group. By nesting projects under relevant paragraphs of the white paper Obsidian will automatically show all these backlinks with context using the Backlinks core plugin. What's missing from Obsidian is multiplayer support, thus I would not know who authored which comment. 

• Similar to project pages, I would also create a template for IT Capability Groups. Those would work very similarly to the logic of the project pages. Each Capability Group would automatically list all the related projects as backlinks.
• I would use dataview to create an overview of all the identified projects. Dataview offers much more control over the table that is displayed when compared to Roam's {{attr-table}}. In particular, I can control the order of columns, and I can define the sort criteria.

```dataview
table 
  it-capability-group as "Capability Group",
  approval-status as "Approval status", 
  stage-1 as "Stage 1", 
  stage-2 as "Stage 2", 
  stage-3 as "Stage 3", 
  budget-2022 as "2022", 
  budget-2023 as "2023", 
  budget-2024 as "2024", 
  budget-2025 as "2025" 
from "Projects"
sort stage-1
```

• Going a step further, I would follow a similar logic for scoping each project. I would link these details to the project. Such linking would ensure that anyone interested in background information could easily traverse through the links to find the definition and roadmap of the related IT Capability Group and the business objectives stated in the white paper.
• It is possible to capture the SAP WBS code as an attribute on the project page, with some coding using Templater I could fetch basic SAP budget data, which I would link to the project by making the WBS/IM Position codes page-links, e.g. [[JBVNANP1]] and importing the data from SAP to the relevant page for the WBS/IM position.
• Finally Obsidian could also auto-generate a visual representation of the Capability Group roadmaps using Mermaid diagrams. For this, I would write a simple Dataviewjs script that collects project milestones from projects linked to each Capability Group and would output the relevant mermaid markup. Similar to Roam, I could also write an MVP in dataviewjs in about an hour. 

Conclusion

In summary, I am comfortable with the Word, Excel, SharePoint solutions we have implemented. It serves our purpose and everyone in my team is proficient in using MS Office. I want the team to focus on the white paper and the analysis, not on the tools they use. These tools get the job done. They are enterprise-grade solutions that have stood the test of time.

If our Information Security team would officially approve Roam or Obsidian, and if I had a team who is already proficient in using either of these tools, then without doubt I would implement one of the alternative solution options outlined above. I believe that the additional context that the alternative workflows provide would pay a good dividend as we move forward with implementing the strategy.

Perhaps someone could implement backlinks and block references using hyperlinks and Visual Basic scripts using Microsoft Office tools. That way, I could have the "best of both worlds", i.e. have an accredited tool, and be able to provide full context to our investment plan and projects with full traceability from strategy to project deliverable. While that is true, we should not underestimate the ease of use. The power of Roam and Obsidian is in the frictionless user experience.

Finally, if you read the article carefully, you will have noticed that in the end, I made no explicit use of block references. If I went down one of the alternate paths of using Roam or Obsidian, I am confident that I would eventually make use of block references, but to my surprise, even though my initial gut reaction was that "I wish I had block references in MS Word...", the workflow I created only uses links, backlinks, and document query features.

Like this post? Show your support.