Skip to main content

Is the best digital workplace just a bunch of Markdown files?

For over a year, I've been working on a major project with a close collaborator. This project has all the complexities of a full product business, meaning we need to define and prioritize what we work on, document our standards, and capture our day-to-day thinking as we work.

There are endless tools that try to create the perfect digital workplace, with all-in-one tools such as Basecamp or Campsite, or communication-specific tools like Notion, Slack, Paper, etc.

After the past year, we've crafted the best digital workplace I've experienced. It has 3 simple properties:

  1. A bunch of markdown files
  2. Neatly organized in folders
  3. Inside the codebase

This approach is absurd—and it works better than any other tool or remote team I've worked with.

Let's dig into how our folders and files are structured, the benefits of this approach, and the intentional tradeoffs it creates.

Second brain as the workplace

I've been a fan of building a second brain for over 2 years now, and it's transformed how I manage my personal and professional knowledge and productivity. I capture all my thinking, learning, and reference into a simple markdown file and folder structure that has scaled to several thousand notes.

A second brain is organized into top-level folders with the PARA method, which stands for "Projects, Areas, Resources, Archives". This approach organizes notes based on actionabilty: Projects are current efforts with a strict work-in-progress limit, Areas of responsibility are ongoing efforts with standards, Resources are reference not tied to a specific effort, and Archives store any past notes from these top-level folders.

Turns out, the PARA method is well-suited for a digital workplace. Companies have projects, areas (business functions, teams, practices, etc.), resources (documentation, reference, notes, etc.), and archives of past work.

So, we added a root-level _second-brain folder with the PARA structure inside our codebase. This centralized everything we do into a single, version controlled repository.

We also do Shape Up, which is our favorite way to decide what to work on and de-risk potential projects. When I learned about the concept of the Incubator from Fractal Productivity, I knew this was the perfect concept to house Shape Up within our second brain.

Here's a breakdown of our full second brain structure:

  • 00-inbox
    • Default home for capturing new notes without worrying about where to put them
      • Perform routine cleaning to keep the inbox tidy
    • 00-tasks
      • Unplanned work (seek to keep this to a minimum)
      • Tasks not tied to active projects (day-to-day work)
    • 01-improvements
      • A log of any potential improvement ideas, perfect for Daily 3S (more on this in the future)
    • 02-scratchpad
      • An outlet for thinking notes and quick/initial ideas to help stay focused on current tasks
      • Informal and no commitment to potential projects or tasks
      • Can create dedicated files for company-wide, team-wide, or per-person use
  • 01-projects
    • Used for active projects
    • Contains all notes related to active work
    • Strict WIP limits (ideally 1 per team)
  • 02-incubator
    • Used for Shape up with framing, shaping, and betting stages
    • Not a backlog! Potential projects are nothing more than ideas until we bet on them.
    • 00-framing
      • Projects that need to be validated for business value and relevant timing
      • Archived if they don't move on to 01-shaping
    • 01-shaping
      • Projects that have strategic value but need to be defined and de-risked
      • Archived if they don't move on to 02-betting
    • 02-betting
      • Projects that are defined and de-risked but need to be committed to
      • Archived if they aren't bet on
      • Projects we bet on are promoted to 01-projects when they become active work
  • 03-areas
    • Areas of responsibility, ongoing efforts, and teams/departments
    • Standard operating procedures by area or practice
  • 04-resources
    • Research
    • Learning notes
    • Documentation
    • Reference
    • Handbook
    • Operations
  • 05-archive
    • 01-projects
      • Completed projects
    • 02-incubator
      • 00-framing
      • 01-shaping
      • 02-betting
      • Projects that didn't make it through Shape Up
      • Helpful to know which stage they were archived
    • 03-areas
      • Business functions or practices that are no longer relevant
    • 04-resources
      • Resources that are outdated or no longer applicable

Benefits

The many benefits of this approach include simplicity, flexibility, cost, security, transparency, centralization, lightness, clarity, and calmness.

Simplicity

The second brain workplace is just markdown files and folders. Files load instantly and are easy to traverse, search, create, update, move, and delete. Markdown has a simple, readable syntax that is easy to learn. There's no custom engineering, infrastructure, or maintenance required.

With simple files and folders, there's no vendor lock-in. Your digital workplace isn't dependent on other companies surviving. There are no proprietary file formats, unexpected changes in features or functionality, or software rot to deal with.

Flexibility

The simplicity of the second brain structure makes it quite flexible and scalable. It's easy to organize and reorganize files and folders as the organization and work evolve.

For smaller teams, it's best to have the root-level 01-projects represent all projects across the organization, with a global work in progress limit. This helps with transparency and creates a more unified focus for the organization.

For larger teams, it's possible to organize projects by area (team or business function), while still setting work-in-progress (WIP) limits per area.

Because everything is just text in a file, it's easy to create new conventions and patterns (which we'll explore below) without having to depend on a vendor to add requested features.

The format of markdown files and folders offers a lot of individual flexibility, as well. Team members are free to use whatever text editor they like, which can be customized with different themes, shortcuts, extensions, snippets, and more. These customizations can be out of preference, need (accessibility), or both. This second brain digital workplace is adaptive instead of only offering whatever features and options a vendor decides to build.

Cost

This approach can be completely free. All the team needs is a open source text editor, Git, and a version control host such as GitHub or GitLab with free private repositories.

Security

Git with SSH credentials is very secure, especially with 2-factor authentication for the version control host. If this approach works for the software a business runs on, it should work well for the company's digital workplace.

Large companies might have an on-prem or self-hosted version control system, which would make this approach even more secure.

Contrast this with trusting another company to secure and preserve your team's internal communications, which might contain proprietary and sensitive information.

Transparency

Having all communications in a centralized, accessible format makes transparency much more attainable. Communications aren't siloed by varying tools or permissions, and team members can easily peruse information across the team.

If this sounds like a tradeoff, then you likely have a cultural issue of secrecy and distrust.

Centralization

This second brain centralizes all relevant information into a simple digital workplace, which increases access and reduces context switching. This helps eliminate waste by making it obvious where information lives (in one spot) and making information quicker to find.

For teams with a codebase, the second brain is even more powerful when it's embedded directly in the main repository. This creates a direct connection between the communication and thinking of a team with the product being built. It also helps achieve the lean principle of "The answer is where the question is asked" by putting all necessary information in the same place as the work being done.

Lightness, clarity, and calmness

This way of working creates ease and quiet in a team.

It's asynchronous, making fewer demands of individual's attention and time. There are no notifications, alerts, or pings. Everyone can access the information they need, reflect on ideas and proposals, and contribute their considered thoughts.

Tasks

At the most granular level of work, teams manage countless tasks for tracking day-to-day efforts.

With Markdown, it's easy to create task lists that can replicate many of the features of task software with simple text patterns:

  • Incomplete task: - [ ] Task title
  • Task with deadline: - [ ] yyyy-mm-dd | Task title
  • Task assigned to someone: - [ ] @assigneeName (individual or team) | Task title
  • Task with deadline and assignment: - [ ] yyyy-mm-dd | @assigneeName | Task title
  • In progress task - [/] Task title
  • Optional task ~ [ ] Task title

With these text patterns, it's easy to do searches in the second brain to find various types of tasks. These searches can be global or scoped to specific files and folders, which is helpful for excluding archived files. They can even be pinned in tools like VS Code for recurring searches.

Example searches include:

  • To do (- [ ])
  • In progress (- [/])
  • Complete (- [x])
  • Tasks with dates
  • Tasks by person or team (@ syntax)

Optional tasks don't appear in these searches by design, because they aren't necessary. But, it's easy to search for them: (~ [ ]).

My experience applying this approach

I've been using this approach for over a year now as I'm building a product with a close collaborator.

It's scaled well across several cycles and projects, many research efforts, countless tasks, and a steady stream of daily ideas, thoughts, and improvements.

Having the digital workplace in the same repo as the code is very natural and eliminates all overhead. You can spend your day in the same tool, reference information with ease, and don't have to manage multiple logins and notification feeds.

This structure also allows for very fluid pairing and contributions. When pairing on work, the driver can stay focused on the task, while the navigator can note future ideas, improvements, and considerations. By practicing the lean principle of "stop and fix", it's also easy to create just-in-time documentation and improve existing notes.

As a big fan of Shape Up, it's felt natural and productive to carry out the full shaping process in the root-level 02-incubator folder, promote active projects to 01-projects, and archive completed work in 05-archives.

For quick coordination and ephemeral communication, we just text each other. This only happens a couple times per week outside of scheduled pairing sessions, where the bulk our work and communication happen. We can easily upgrade this to a tool like Discord or Slack in the future, albeit with very limited use cases.

Tradeoffs

This approach has its tradeoffs, but they are minor. Some are also intentional advantages.

One piece of anticipated pushback is this approach requires everyone to learn Markdown and Git. I'd argue there's a learning curve to any tool, and these skills are much more widely useful and transferable than learning the quirks of a specific workspace tool that won't be around in 5 years or won't be used in a future role. Markdown is easy to learn within a session or two, and while Git can be quite complex, a second brain typically only requires adding files, committing them, and pushing/pulling. I wouldn't encourage using branches or other advanced version control approaches. This can also be a form of skill-leveling across a team, by giving non-developer team members some bridging skills. If the second brain is colocated in the main codebase, this also gives team members the ability to explore and learn how things are being built.

There isn't a way to make fancy content blocks or layouts, such as tables with filters, data plots, Gantt charts, etc. This is fine for me as I prefer lightweight, simple text over complex visuals, and the time invested in crafting the perfect Notion template or a color-coded multi-view database is largely waste.

There's no great way to handle images. We rarely need to include images, so our solution is to just put them in a folder colocated with a note. Text is lighter, more accessible, and editable, so images are often unnecessary.

Internal linking is clunky between notes, especially if relative paths change as files and folders are moved. Wiki links would be great, but would involve more complex tooling. Luckily, linking between notes hasn't been a frequent need.

There isn't a great solution for mobile access. GitJournal for Android is one example that works decently for a second brain, and there are likely equivalents for iOS. But it's probably healthier to not have the workplace accessible from a phone in the first place.

Same-document, real-time collaboration isn't possible. This is solvable by having a designated scribe during calls who is sharing their screen, similar to pairing. Collaboration in general is a solved problem, since Git resolves conflicts and companies can obviously develop massive codebases at scale using the same tools and practices.

As mentioned above, this approach is not well suited for quick coordination and ephemeral communication. That's better handled by a chat tool, and that chat tool's purpose is greatly clarified to only be used for a quick question or reminder. Everything else should live in the second brain.

Lastly, this approach doesn't allow private communication or private personal notes. Direct communication might be better handled by a chat tool, and anything beyond quick coordination should ideally be part of the second brain.

Personal notes can be handled by team members maintaining their own second brain for their role. This is actually how I came up with the idea of using a second brain at a team level, as I've created a second brain for each long-term client engagement and my current full-time role. A personal second brain for my role has been essential for making sense of the chaotic communications that occur across teams in many different workplace tools. Having all communications in a team-wide second brain would greatly reduce the need for personal notes.

It's also possible to create files and folders for specific teams and individuals if the information doesn't need to be private. For example, it might be useful for each team member to have their own scratchpad for in-the-moment thoughts or thinking notes.

Wrapping up

I'm confident there's value in this approach and the past year of using it for a major project only makes me more excited to keep going.

It's strange that this approach would be considered radical because of its simplicity. Most organizations believe they need tons of complexity, almost as evidence of sophistication, and never reflect on what's essential. Most organizations aren't aware of the waste caused by having several heavy, cumbersome, and expensive communication tools as their digital workplace. There is so much time, money, and effort over-invested in these tools that are really just glorified text documents. There's a lot of value in cutting away all the unnecessary and just managing a simple file and folder structure.

I'm interested in hearing your thoughts on this approach, especially if you try it for yourself or your team. Let me know what you think: team@buildux.co