We may ask ourselves what is the best way to store software documentation? Where should we store software documentation? As with each of such questions, the answer is usually: “It depends”. Depends on what? Well, plenty of factors. I described many of them when trying to answer the question of how to choose a tool for software documentation. This time however, I would like to explore possible locations where we can keep our knowledge and manage it effectively.
Let’s start by identifying some guidelines:
- Our documentation should be easy to find, easy to read, and easy to write.
- We don’t want to install additional software required to access it.
- It should be possible to edit by as many people as we want.
I identified two major groups of possible locations, which I will explain in more detail below:
- Source code
- Other systems
- Q&A tools, internal forums
- Document files
- Collaborative boards
- Diagrams
- Dedicated software for knowledge management
Source code
There is a pretty high chance that if you work in a software company, you use some kind of version control system like for example git (including tools like GitHub, Bitbucket, GitLab). We can utilize its benefits to store the knowledge together with code.
Benefits
What are the benefits of storing documentation together with source code? Should you keep your software documentation in e.g. GitHub?
Documentation is closer to the source code. When you come across a piece of code, that you don’t understand the context behind, you may find the documentation explaining it more easily, because the file sits next to the code it describes.
You get a history of changes. It’s not so simple to accidentally delete important documents. You know who edited what and when, in case you would like to ask follow-up questions.
You have a tool for diffs. Not only can you make a code review but also a docs review. It’s easier to comment on specific lines when you have a side-by-side view of changes.
You can build automation on top of the documentation. Because the documentation is made of text files and it sits together with the source code, we can supercharge our documentation pipeline, and for example, generate themed docs pages, or notify people on chat when there is a new documentation update.
Portability. Chances are the documentation is mainly built from markdown files and images. That means that if you want to migrate to the other tool, it’s very easy because these file types are universal.
Downsides/costs
Of course, there are also certain downsides to using source code tools as a knowledge repository.
People need to use git efficiently. If the documentation is written and updated only by software engineers, that may not necessarily be a problem. However, if there are fewer technical people on board contributing to it, the learning curve may discourage them from doing it.
You need to pay for user accounts to maintain the docs, even if they don’t contribute to the codebase. This is similar to the point above. If there are only software engineers, that’s fine.
You have only basic formatting features. If you work with markdown files, you’re limited to its capabilities: headers, lists, tables, etc. You won’t be able to use mentions syntax (@username), and in case you link to other pages/documents you have to maintain the links by yourself (unless you have some tooling in place). You also won’t get interactive components e.g. expand/collapse.
Searching is optimized for code. These tools were primarily built for storing code, so the search may not be optimized for looking for knowledge – e.g. looking for similar words or with typos. That, however, may change over time as the version control tools mature.
It’s spread across many repositories. If your organization doesn’t follow a monorepo pattern, you have documentation spread across multiple places. That also brings a challenge, where you should store the docs that describe the code of multiple services.
Wikis
An alternative to keeping the documentation directly with the source code is keeping it in the repository’s Wiki. It still preserves the benefit of revision history and has a nice Markdown editor.
But there also still exists the same challenges related to where to keep the documentation. If you have multiple repositories, it’s not clear which one should have the wiki.
One option could be to have a dedicated repository, just for the overall product documentation. That of course takes away the benefit that the text describing the code is closer to the code itself.
Other systems
Source code is not the only place where you can store your documentation. Especially if we deal with documents that describe the business knowledge rather than the code. What are the possible alternatives to source code that we can use to store the knowledge?
Q&A tools, internal forums
An example could be Stackoverflow for teams. The idea is that some people ask questions, and others respond. Then, employees can find what they need using search or suggestions when creating a post.
This is by no means a structured way of transferring an organization’s knowledge. It’s more problem-oriented than learning-oriented. It can be useful for people trying to solve a specific problem, but not really in cases when you want to get a high-level overview of what’s going on in the team/service/business domain.
In some cases, Slack, or other messaging tools could serve this purpose, as long as the company follows some best practices of using such tools in remote work, and makes the communication public.
Document files
Companies may already use enterprise solutions like G Suite or Microsoft 365 for Business. That means that they already have document tools at their disposal (e.g. Google Docs).
They have multiple benefits:
- The files and the content are easy to search and easy to share.
- Editing is also very easy. More components are available than in the case of markdown files + the WYSIWYG editing tools are more visual and straightforward for many people.
- Additionally, we can extend the capabilities with plugins – either custom or from the marketplace.
The downside is that it may not be convenient to scan through multiple docs, especially in cases when we don’t know what we don’t know yet, and we want to build a high-level picture in our minds. For example, Google Docs miss the sidebar with all documents in the directory.
Moreover, a shared space may be required, otherwise, we end with documents spread across multiple people’s accounts. And the shared space involves an additional challenge of maintaining a structure. If everyone is responsible for it, then no one is.
Collaborative boards
Covid made remote work very common, which resulted in the huge popularity of remote collaborative board tools like Miro or Mural.
One big benefit of such tools is how easy it is to use them. They offer a variety of visual components that make the board more appealing. On the flip side, it also makes them a bit unstructured. People tend to introduce multiple ad-hoc conventions during collaborative sessions, which are not understandable for people accessing the board in the future.
Also, it may not be the best place for storing text content, so it makes sense to treat collaborative boards as a supportive source of documentation.
Dynamic by their nature, it is also very hard to preserve the history of changes.
Does it make sense to keep documentation in Miro (and the like)? What can it be good for?
- They are very good at explaining the business flows (e.g. event storming sessions).
- Can serve well as the ad-hoc architecture diagrams
- They are very useful for feature design sessions.
Diagrams
Tools like draw.io or lucidchart are good places to store diagrams. Sometimes it is just easier to express certain ideas visually.
But the diagrams by themselves may not be enough for the whole documentation – it may not be optimal to keep text documentation in diagram tools (e.g. due to optimized text search or lack thereof). Instead, it makes more sense to link the diagrams in the text documents written in other places.
Some tools enable exporting and importing files (e.g. Excalidraw). With that, you can create diagrams, export an image and embed it into the document together with its (the diagram’s) source code. This way, the next time someone wants to edit the diagram it’s easier. Just imagine a scenario when you wanted to make a small update to the documentation but it would make the image outdated. And the image is just a screenshot, and you don’t have access to the original diagram so you would have to recreate it, just to make a small adjustment. That can discourage people completely from keeping documentation up-to-date.
One subgroup of diagrams tools could be diagrams as code. This is a declarative way of creating diagrams. Instead of creating them with the visual tool, and then exporting them, rather we define them in the code, and then a special renderer converts them into an image.
Some examples of these declarative diagrams are:
- Mermaid – that allows you to create for instance flowcharts or sequence diagrams,
- Structurizr – works well with a C4 model for visualizing software architecture.
Over time, certain documentation tools add new features and integrations that are capable of rendering these declarative diagrams into images on the fly e.g. Mermaid plugin in Confluence or GitHub that can render Mermaid diagrams in markdown files.
Dedicated software for knowledge management
These could be further divided into two subgroups.
- Internal wikis – tools like Confluence, or Notion, where the organization’s knowledge is kept
- Knowledge base – often used by customer support to collect common issues, so that customers can solve their problems by themselves (e.g. FAQ pages). Examples:
I grouped them together because they share common characteristics:
- They often have pretty advanced content editing capabilities
- They usually have well-optimized text search
- They introduce additional means of organizing the knowledge e.g. tags, or special dynamic pages e.g. databases in Notion, or auto-generated pages in Confluence
They may also have some downsides e.g.
- you keep your organization’s knowledge in the external organization that may not be as well established
- you introduce one more tool to learn, manage, and pay for.
- often the content is not portable. Once you start putting the organization’s knowledge into them, it’s a lot of effort to migrate away.
I described more potential aspects to consider when choosing the right tool in the article: how to choose a tool for software documentation.
Takeaways
In the article, I described a few potential places where we can store our documentation.
Source code – it is a good place to keep pieces of knowledge closely related to the code. It makes more sense if the documentation is maintained by engineers who are already able to use git efficiently. Most likely the documentation itself is written in Markdown, which is a very universal format and makes the documentation portable to other systems.
Repository wiki – is an alternative place. We maintain the benefits of a version control system like revision history. However, the documents are already a bit far away from the code. We also have to decide in which repository we want to keep the documentation (in case we have multiple ones).
Q&A tools, internal forums, chats – a bit unstructured, yet problem-oriented way of preserving the knowledge within the organization.
Document files – easy to edit, search, and share. They come with the enterprise solution that the company may already be using. Basic features can be extended with custom plugins. The challenge is how to structure the files in a shared space and how to navigate through multiple files.
Collaborative boards – visually appealing, very easy to use, however very dynamic, may not be the best place to store mission-critical organization’s knowledge – especially in written form.
Diagrams – a great way to support text documentation. Some tools enable exporting diagram files which makes future edits easier. Certain diagram tools allow us to define diagrams as code and render images on demand.
Dedicated knowledge management systems, internal wikis – they have advanced content editing capabilities, well-optimized search, and additional means of organizing content. However, that comes at the cost of introducing (and paying for) yet another tool.
