What is documentation?

A company’s documents, also referred to as a company’s knowledge base, or a Wiki, and for short: “docs”. Are the central, accessible, written information about the software this company builds, its business use-cases, future plans, historical or deprecated plans, post-mortems, environment setup… etc. Sometimes docs extend to a company’s business values, goals & mission and other fluffy stuff. You can think of docs as the internal internet for a company, or internal Wikipedia. In short, docs for a company are the central source of information on what they do, how it’s done, and -maybe- why. No, Slack threads aren’t docs.

A type of docs is the publicly accessible information about a service, or: Software Usage Docs. This is what us engineers usually call docs. Such as Streamlit.io’s API docs, or Notion’s guides. A common misconception is that such documents are all what “docs” are. However, they are only a subset of the general knowledge of building and maintaining software. What we commonly refer to as docs are either user-docs (how a user can use your service) or developer docs (more technical, but still cover how a type of user - developer - can use a service). The other types of docs can be understood in comparison to Usage Docs. In gist, just as users of your service need docs to understand it and use it, your engineers need docs to understand how it’s built and contribute to it.

An Analogy

You know when you start learning Flask development, you google “how to setup Flask development env?”. Well, in an established team of engineers, they have their own combination of tools, frameworks, and preferences to develop their tech. That’s knowledge you can’t find on the internet, because it’s specific to your company. That’s the kind of question a knowledge base should answer, “How do I set up my environment?”.

Example: New-Joiner Guides

These are one of my favorite examples of docs.

New Joiner Guides - form the name - are aimed at new-joiners. Depending on the amount of time you had to write them, they can cover subjects from “meet the team” to “here’s an outline of how our codebase is written”. What I mean by “Meet the team”, is a post about who the team members are, with their titles, roles, and responsibilities. Some other docs that go deeper are subjects like “Repo Structure” where it’s laid out which service/engine is stored in which repo and who maintains what, etc.

Now, why are new-joiner docs my favorite? For two reasons. First, you think you don’t need them. Because by definition, as a team-member, you believe this knowledge to be trivial. However, it’s only trivial to current members. You’ve been part of this team for some time now, you know people’s names, you know what they do and how they relate to you, and you know which repos store which code. And you also forgot how painful it was to collect this knowledge when you first joined. Second reason is They are very easy to write. like I mentioned, this is information already known to the entire team (hopefully). Anyone can contribute these docs. They are not technical neither complex. All they need is the time and initiative to write up. And, if you’re thinking of starting a knowledge base mid-way through this post, they’re a very good first-doc in a knowledge base.

New-joiner guides might be used just the first 2 weeks someone joins, and then never opened again until someone new joins. But do not underestimate their use-fullness for a new overwhelmed and probably lost team member. These can be grounding guides and good references. Especially for those insecure of us and afraid to ask about seemingly simple information.

One easy method to start writing new-joiner docs is to reach out to the most recent new member, and ask them to write down what they thought was valuable information that wasn’t reachable right away. Or even better, ask the next new joiner to contribute to that document after they’ve found the answers.

Example: Business Requirements’ Docs

That was a simple example, but docs can be a little bit more complex. How many times in your experience has a feature been implemented wrong? As in, does not meet the business requirements. How much time and money did that cost? Almost always, the reason this happens is lack of communication between teams. In this case the business team and the dev team. Proper docs should solve this. In my opinion, all business requirements should be documented before starting their execution. An engineer is not going to remember the edge-cases you highlighted in a 3 hour product brief. These are called Requirements Docs. they take many shapes and some other names like Functional Specification Docs, but the goal is one: to serve as the ground truth between business and execution.

Example: General Knowledge

Another example of docs is general knowledge gained. Either domain-specific or tool-specific. This is especially useful when working in up and coming markets, where a lot of the services you’re building upon are poorly documented, or maybe you’re trying to digitize a domain from scratch. Are you using a poorly-written API with some unexpected behavior? Document that behavior. Is the domain you’re working with lacking knowledge that you gained after reaching out to people and spending time investigating? And is now stored in email threads? Document that in your knowledge base. Any jargon or terms? Write them down. An odd seemingly arbitrary way some piece of code is written that doesn’t make sense until you learn that it’s built on x… write that explanation down. Share it, ask for feedback on it, and iteratively update it.

Using Docs to Avoid Single Points of Failure

An additional important vertical docs help with is single points of failure. A single point of failure in a software team is a member so critical that if they suddenly disappear, the impact caused is significant enough to hurdle either your current operations or your ability to ship work in the future. Either they built a big chunk of the codebase on their own, or they alone were responsible for handling an important client, or they dealt with this specific domain… etc. These are people if they leave the team, you lose a significant (maybe crippling) amount of knowledge, because it was only documented in their heads.

From the team you’re working on, how many single-point-of-failures do you have? If the answer is above zero, you might want to consider revising (or starting) your knowledge base.

How are Knowledge Bases Built?

This is a broad topic that I plan to write about in detail, but some trivial general practices are things like keeping them up to date. No knowledge is worth much if it’s out of date is it? Another good practice is developing the docs collaboratively. Rarely is all knowledge about a tool, product, or service contained within one team member. It’s fruitful to draft a doc and share it around, asking for feedback and revisions. An important point to keep in mind is try to keep the knowledge base organized, easily searchable, and simple to understand. That’s why I noted earlier that Slack or email threads are not knowledge bases. If it’s accessible to a small set number of people (like only people in an email thread or members of a Slack channel) that’s not documentation. Mostly because it’s distributed and private in nature, when, a critical feature of a knowledge base is that it’s central and accessible. Knowledge bases can house sensitive information, therefore proper tools for building them allow for access levels. Where for example one team is restricted the access to a subset of sensitive docs. Which is fine, that doesn’t go against accessibility of information as long as the spirit in which these access rights are granted is good to know, as opposed to need to know.

Knowledge Base Tools

Another general practice is to use the right tool. PLEASE do not document your knowledge using MS word docs… that’s an unmaintainability trap. Word docs might produce pretty documents, but are known for being bad collaborative tools and possess one of the worst version control systems I’ve seen (did you even know they had one?). Use cloud-based tools that are designed for collaboration.

• The first that comes to mind (which is the tool I use to write this blog) is Notion.
• Another popular tool is Confluence, mainly because it integrates well with the software/product the knowledge base is about (too well if you ask me).
• A minimal tool I’ve used for docs is Slab.

These tools make collaborating, organizing, maintaining and sharing a knowledge base easy.

Summary

I hope it’s clear by now why docs are an important pillar to assess a company’s fit for oneself, and why I’m a huge advocate of them. But let me recap that in points:

• Docs reflect the maturity of the company. The fact that engineers are given time to document their work shows that management understand the basics of working on software.
• Docs reflect the competence of the team. If you can’t explain how a thing functions, do you really understand it?
• Docs reflect culture. The style in which docs are written is a reflection on the culture in which they’re written. Are they full of jargon and unnecessary complexity? Or are they simple to understand and straight to the point? They’re a good survey on your culture, and a good tool to build a collaborative one.
• Docs save time and effort for everyone. By being a single source of truth between distributed teams.
• Docs minimize reliance on single-point-of failure members.

And, most importantly:

• Docs retain and build knowledge.

Docs are usually overlooked because they don’t seem to produce tangible value. However, they’re quite critical to productivity and a healthy work-culture. Docs should be simple, but that doesn’t mean they’re simple or straight-forward to write up. For docs to have value, they have to be clear, organized, have a specific target audience, and up to date. Not a simple feat, but worth the time and effort.

Thank you for reaching this point in this post! For any discussions / suggestions or feedback, feel free to reach out to me on Twitter.

Photo by Gabriella Clare Marino on Unsplash