Proper Documentation

Thanks for reading this issue. For everyone who joined recently: this is a very subjective newsletter about all things surrounding engineering management / CTO daily life.

I'm grateful for the 152 new subscribers that joined since the last issue, which was 3 weeks ago (again!). Sorry about that, life got in the way. I'm currently in Bali, and the environment here is not aligned with my work mood. Everyone who works from Bali, how do you do it?

Share this article with your friends, here's a link.

You can also discuss this article on Reddit and HackerNews.

I’m a big fan of documentation. I think it’s my favorite boring thing to do after coding. It brings the business so much long-term value that every hour invested into documentation by anyone saves literally x100 productivity hours across the company.

If you’re a CTO, documentation is your secret weapon, the unsung hero of your startup, the gray knight, which keeps things going behind the product development. It eradicates guesswork and reinvention of the wheel. Think of it as your golden ticket to suuuuper fast onboarding. This treasure map guides newcomers and veterans from other departments into the labyrinth of your startup's processes. Your team will find their footing faster, becoming effective contributors sooner, and work more effectively than you'd expect, all because you decided to prioritize writing down stuff.

Here’s a question for you, which is better:

1. Writing someone an email, knocking them out of their focus zone, asking to explain how a piece of software works
2. Or looking up the necessary information yourself and processing that at your own pace.
   Hint: It’s the second one.

Importance of Documentation

Let’s start from the basics.

Imagine you’re a technical co-founder at an early-stage startup (or maybe you don’t even need to imagine), and you’re drowning in chaos, as is expected. You’re playing whack-a-mole on a daily basis and are just trying to get a single breath of sanity before being pulled down into yet another issue. How do you get out of this spiral? The answer is simple — documentation. Now, I'm not just talking about maintaining a simple how-to manual or jotting down meeting minutes; Those are also important, yes, but I mean building a culture where knowledge isn't confined to individuals but is dispersed and accessible to the entire organization.

Every single thing that is not written down equals wasted resources in the future and a potential for headaches. Your headaches. And I don’t know about you, but I’d like to make sure I don’t have any headaches; that’s why I enjoy building systems that work without me. Now imagine how much stuff you haven’t written down yet, and that’s your current potential to drown in unexpected issues. For example, your continuous deployment broke because of some package updates. Coincidentally only Bob from Department X knows how to fix this issue. Oh, and they’re on vacation this whole week.

You can think of Documentation as essentially the backbone of effective knowledge sharing. In the early stages of a startup, when you’re the only one coding and building, sharing information and insights can be as simple as chatting with your CEO across the desk. You have the knowledge and the means to fix something if it breaks. But this is exhausting, and you’re basically the limiting factor of the company. If you go on vacation — scratch that; you’re not going on vacation because everything will stop if you do.

As the startup scales, the number of people, projects, and complexities increase exponentially. The knowledge gets siloed in your head, communication becomes convoluted, and before you know it, people are spending more time hunting you down for information than actually using it. If you’re a technical co-founder - extract every bit of knowledge that you can and put it into writing. This will serve as a universal source of truth, a dynamic repository that captures and preserves collective wisdom. This wisdom can help everyone on the team solve issues they had no idea how to solve a minute ago. And this will also allow you to take a vacation. Trust me; you need it.

Documentation first, meetings second

So now that you know that documentation makes your life easier and not harder, let’s talk about time and efficiency.

In the world of startups, time is the ultimate currency. Each tick of the clock carries the weight of decisions made, products built, and markets conquered. And meetings are notorious thieves of this currency. Don't get me wrong. I'm not saying that all meetings are evil, but we must critically scrutinize their cost against their value. In the words of Bukowski, "Don't do it unless it comes out of your soul like a rocket," apply the same principle to meetings — don't hold them unless necessary.

The constant need to have meetings is a symptom of a deeper problem — a lack of clear, accessible, and reliable documentation. A well-documented workflow doesn't need an hour-long session for clarification. A well-documented decision doesn't need a room full of people to understand its rationale. A well-documented knowledge base doesn't need a group huddle whenever a new member joins the team.

"But aren't meetings essential for communication?" Yes, they are. But too many of them, especially the poorly managed ones, can cripple your startup. They create an illusion of productivity, while in reality, they are stunting it. By reducing reliance on meetings and emphasizing documentation-first asynchronous communication, you're empowering your team to communicate effectively without being bound by the confines of a Zoom call.

Think about it: every unnecessary meeting is a missed opportunity. It's time that could have been spent refining that crucial algorithm or simply taking a moment to recharge and prevent burnout. In essence, reducing the reliance on meetings isn't just about reclaiming time; it's about reclaiming the ability to focus, innovate, and create — the very lifeblood of a startup.

As a CTO who's been through the fiery crucible of startup growth more times than I care to count, I can assure you: your time and resources are better spent documenting than on meetings. Most meetings could easily be replaced by a well-drafted document that presents the relevant data and proposed solutions and invites feedback.

Also, meetings often favor the loudest voices, not necessarily those with the best ideas. It's a subtle form of bias that can stifle innovation and diversity of thought. Documentation, on the other hand, levels the playing field. It provides a platform for every team member to articulate their thoughts and insights, regardless of rank or communication style. It promotes a culture of thoughtfulness and reflection rather than snap judgments and impulsive decisions.

You might think it’s a good idea to have a company-wide meeting where you announce that you will integrate AI into all the processes starting now. But is it? In the adrenaline rush of being part of a fast-paced startup, it's easy for details to get lost in the whirlwind. You mention something, you make a joke, you mumble and miscommunicate, and before you know it, you have another issue on your plate that needs solving. Writing down the decision and how it came to be equals clarity.

Every decision is a brick in the foundation of your growing startup, and documenting them can provide a solid record, a kind of architecture blueprint that details your thought processes, concerns, and rationale. This clarity can be invaluable as you scale and face increasingly complex challenges.

When you introduce documentation into your decision-making process, it acts as a knowledge repository. It holds the context, the insights, and the learning that came with each decision. And this repository can be referred back to when similar situations arise. You can reference them. This, in itself, is a sustainability hack.

Now, as a CTO, how can you facilitate this? Encourage your team to document their decision-making process to clarify assumptions, reasoning, and expected outcomes. Make it a standard practice to discuss these documented decisions in your meetings, promoting a culture of open feedback and collaborative decision-making.

The beauty of this is that it turns every decision into a learning opportunity, fostering a growth mindset within your team. It allows everyone to see the consequences of past choices and understand the considerations behind them, making them better decision-makers.

Building a documentation-first culture

Documentation-first culture means cultivating a shared consciousness in your startup, a unifying force that links everyone together. This isn't just about some rigid adherence to process — it's about democratizing knowledge, breaking down hierarchical barriers, and fostering a learning culture. A documentation-first culture does not mean everyone is busy writing documents all day. It means that everyone appreciates the value of documenting and sharing their experiences.

What it also means, of course — when building a project, always account for documentation as part of ANY task. It should be a default that some percentage of employees’ time goes into writing down their stories. It's not just about efficiency — it's about creating an environment where shared knowledge is celebrated. It's about creating a culture that doesn't just create a product but crafts a story — a story of collective growth.

Your role in this can be as a catalyst and a facilitator. Always start by setting an example. Document your own processes and decisions and share them openly. Take notes, always. Encourage a culture of feedback and learning, where every document is a starting point for discussion, improvement, and innovation. If a decision needs to be made, start with a document, not a meeting. If there’s a pros/cons discussion — start with a document.

As a CTO, people will look up to you and do as you do. Because everything that you do in the context of your company is the right way to do it, this is a double-edged sword, so be careful with what example you set for others.

By encouraging your colleagues to document their processes, decisions, and learnings, you're showing that you value their insights and experiences. This fosters a sense of ownership and engagement beyond their designated roles and tasks. They become active contributors to the company's knowledge base and its success.

Give praise to those who write good documentation. Share it publicly. Congratulate those who are as enthusiastic about documentation as you are.

The tools

Next, give tools to your team members that make documentation a breeze. Find a tool that fits your team’s needs and workflows, whether a shared drive, Notion, Confluence, Gitlab, or some other knowledge management platform. There are hundreds of them. Remember, the easier you make it for your team to document their work, the more likely they are to do it.

Prepare templates AND guidelines. Think of them as the DNA of your documentation - they provide the structure, consistency, and predictability that allow your knowledge to replicate and spread effectively throughout the organization. This is a complex and time-intensive task, but once you have them, it gets easier.

Templates ensure the information is recorded in a standardized format, making it easy to understand and compare. On the other hand, guidelines provide the 'rules of the game,’ ensuring that everyone understands what to document, how to do it, and where to find it.

Promote documentation as a part of your company's values. Encourage your team to see it not as an additional chore but as an integral part of their work, as vital as writing code. Make it a routine part of performance evaluations and feedback sessions. Ask them to improve it, and ask them to find flaws in your processes.

As your startup evolves, so will its documentation needs.

Dedicated Team

Designating a dedicated team or individual for documentation in an early-stage startup can seem extravagant. But trust me, it’s one of the smartest investments you can make. Why? Because knowledge is the lifeblood of your startup, and a dedicated handbook team acts as the circulatory system, ensuring that this vital knowledge flows freely and efficiently throughout the organization.

The benefits extend beyond mere knowledge management. Your documentation team can enhance overall organizational effectiveness by bridging gaps between teams, facilitating cross-functional collaboration, and breaking down silos. They serve as the glue that binds all your team brains together.

Change will bring pushback

Not everyone is going to like it. If you’re an established startup with a few years under your belt, there will be pushback. Remember, you're not just dealing with code; you're dealing with people. Their fears, comfort zones, and hesitations are as real as any technical bug. They need to be addressed with the same level of patience.

One of the most effective ways to deal with resistance is through engagement.  Listen to your team's concerns, understand their perspectives, and address their fears. Show them the benefits, efficiencies, and liberation a documentation-first culture can bring. And I’d like to repeat — model the behavior you want to see, be the first to document, to share, to learn, and show them how awesome it can be.

Celebrate those who adopt this culture — their wins, efforts, and strides toward a documentation-first approach. This not just encourages them but also inspires others to follow suit.

It’s not that “not everyone will like it” is your only problem. The documentation itself will also not be perfect and might be pretty bad at the start. That’s okay, don’t panic. Remember, it’s a living organism that takes time to evolve. As a CTO, your role is to ensure that the quality of your documentation grows over time. This isn't about policing. It’s about cultivating.

What qualifies as good documentation

This is more of my subjective thoughts on how good documentation looks like.

First off, clarity and conciseness. It's about breaking down complex concepts into digestible bits, trimming the fat, and focusing on what matters. Your document isn't some long-winded novel; it's a guidebook that others need to follow.

• For example, in Notion, you can emphasize information in different ways.
• If it feels too dry, it needs to be rewritten.
• Add Illustrations and video explanations.

Then comes structure and organization. You need a format that makes sense, that's intuitive. If people can't find what they're looking for, they'll get lost and frustrated. Your document needs to guide them, not confuse them.

• Break it down into pages and cross-link related documents.
• Build a table of contents.
• Next / Previous — suggest which other document might be helpful.

Next up, accessibility and discoverability. Your document isn't some secret tome hidden in a dusty old library. It's a living, breathing resource that needs to be easily accessible and discoverable.

• Utilize tags and categories, and segment your information into different clusters.
• Utilize full-text search or AI vector search

Lastly, and this is critical, your document isn't a monument. It's not something you build once and forget about. It's a growing, evolving entity that needs regular updates and maintenance. Your organization changes, your knowledge expands, and your document needs to reflect that.

• Track the last changed dates, and update those older than a year.
• Track who the owner of this information is, and update it regularly.

Here are a few open-source documentation systems that I recommend studying to get some inspiration:

1. Gitlab — Gitlab handbook is 2000 Pages of Documentation that is version-controlled and is constantly updated. Highly recommend reading through it.
2. Strapi - Inspired by the radical transparency of Gitlab, also good documentation to read through.
3. Remote.com - Another good example

Not a silver bullet

I've been singing the praises of documentation for a while now; thanks for reading this far, by the way. But let me put down my pompoms for a minute: Documentation, while impressive, is not a magical cure-all. It won’t swoop in like some superhero and rescue your startup from every problem. It's a tool; like any tool, it has limitations. You’re still going to be dealing with issues… but less.

Documentation, while a boon for collaboration, is not a substitute for human interaction. It cannot replicate the nuances of face-to-face communication, the value of immediate feedback, or the bonding when a team huddles together to tackle a tricky problem. The camaraderie built during these meetings or even informal catch-ups is vital for fostering a healthy work culture and driving team motivation. If you swap all human interaction for a series of documents, you're setting up your team for isolation and disconnection, a one-way ticket to low engagement.

The process of documenting itself can be time-consuming. There's a certain art to writing a practical, concise, and easily digestible document. It requires thoughtfulness, clarity of thought, and a knack for simplification. Some might argue that the time spent crafting these documents could be better utilized elsewhere. And they're not entirely wrong. If you're documenting every tiny detail, you will have an overwhelming library of information that's as difficult to navigate as a dense jungle and might not be THAT useful.

Lastly, despite your best efforts, documentation can quickly become outdated. Technology evolves, processes change, and what was relevant a month ago might not be relevant today. Keeping your documentation up to date requires constant vigilance and regular maintenance, which can be challenging for a rapidly growing startup with limited resources.

Conclusion

My advice to all the young tech enthusiasts, future engineering managers, and CTOs is simple: cultivate a love for documentation. You may view it as a chore, an afterthought, or a nuisance. But trust me when I say this: Documentation isn't just a task on your to-do list; it's a pillar for success and a bridge that connects ideas, people, and vision. Treat it not as a burden but as an opportunity to learn, share, and create an impact.

Start small, but start today. Don't wait for a grand strategy or a perfect tool. Start by documenting your code, your decisions, and your learnings. Make it a part of your daily workflow, not an end-of-the-day chore. And as you move forward, imbibe this culture of documentation into your teams, your projects, and your organization. Create systems and processes that encourage and facilitate documentation.

If there’s one thing you can take out from this article, carry this mantra with you: "Document to empower, document to grow." Embrace this philosophy, and you'll be surprised at the transformations it brings, not just in your career but in how you view and navigate the world of technology.

Cheers,
Vadim

Older Issues:

• Rules of Thumb for Software Development Estimations
• Things they didn’t teach you about Software Engineering
• Contracts you should never sign
• Software Development is very subjective