One of the most needlessly time-consuming tasks that your team members can engage in is looking for information on work that has already been done by somebody else. Perhaps a developer is seeking to perform an oft-repeated task like the creation of a new microservice. Or a new employee on the team needs guidance regarding designing a product roadmap and wants to look at one that was made for a similar project. In either scenario, it would be foolish to start from scratch or spend hours sifting through mismanaged documents. Good document management through proper documentation comes to the team’s rescue in situations like these so that your employees can continue to work efficiently and deliver reliable software.
In this article, we discuss how you can effectively put together documentation for your projects and incorporate the practice during the starting point of your software engineering culture. We do so by highlighting the importance of having a documentation practice and outlining a few steps that will help you get started.
What is internal documentation and why is it important?
Internal documentation refers to the record of various processes and best practices that are carried out and followed in a company. While external documentation consists of guidelines and resources about important topics for use by people outside the company, internal documentation is meant to be used by employees. This can be, for example, to replicate a process that was carried out for a project in the past.
This practice serves many purposes and it is helpful for people across the company to have access to internal documentation. The following are a few reasons to invest in internal document management.
Smoother onboarding
New hires are bound to take some time to adapt to how their team works and to understand what is expected of them. However, too often, their struggle begins at the timeline where they have to find the information and resources that will familiarize them with their new environment. Having robust process documentation fixes this to a large extent.
Although it cannot act as a substitute for mentorship and guidance from both seniors and peers, having team documentation at their disposal helps new team members have basic technical and operational questions answered and gives them a strong footing to stand on. When they know exactly what to look for and where they will find it, they can directly move on to understanding the information in front of them and using it appropriately in their work.
They can then supplement this with tutorials and mentorship from others on the team. This also lessens the burden on older members to hand-hold the newcomers throughout the employee onboarding process.
Increased productivity and efficiency
Internal documentation, when compiled diligently, can be immensely useful. In addition to the benefits it has for new members, it also makes it easier for anyone on the team to replicate a process that was carried out in the past.
If, for instance, a team member has created a microservice that somebody else wants to review for the processes involved or reproduce, they can look at the project documentation and follow the requisite steps to achieve this goal. This saves the time and effort that they would otherwise spend trying to figure out the process despite the fact that it would not have been significantly different from what had already been done. The team is not only more productive but benefits from a smarter workflow. Because documentation is meant to cover the development and standard operating procedure extensively, this can also be applied to tasks like scheduling meetings and filling out meeting agenda templates.
In addition to helping developers avoid unnecessary repetition in their workflows, setting up software documentation also achieves a certain degree of consistency across the team or organization. When standard ways of doing specific tasks are established and made easy to follow, there are fewer discrepancies, and the software is built more cohesively. Managers and engineering leadership also have a considerably more straightforward project management experience.
Circulation of knowledge
Over time, teams and individual employees accumulate a wealth of internal knowledge by way of their work. This information is sometimes informally exchanged within the team, but with no documentation, it is more likely to be lost quickly. It is a great loss to the team when the knowledge held by an employee leaves with them in the event that they leave the company. Other members or new members are, as a result, forced to reinvent the wheel.
Documentation helps preserve such knowledge for years, ensuring that teams continue to benefit from the knowledge sharing and learnings derived from what they have worked hard on for a long time.
How do you set up a documentation system?
Putting together documentation can initially be a slightly involved process if your company is just getting started. To help you get the foundation in order, here is a step-by-step overview of the process.
Identify the reasons
Right before you start setting up an internal documentation practice, you should understand why you are keen to invest in it. The reasons vary across teams depending on how they function and what their needs are at any given point. Some motivations for establishing a robust documentation practice are:
Your team is growing rapidly, and you are worried that you are going to lose context.
Other teams should be able to come in and understand all your services.
You want your own team to understand the existing services architecture better.
To ensure smooth and hassle-free onboarding.
Figuring out your own motivations is step one because these will guide your actual documentation strategy. For instance, if you are more concerned about ensuring a smooth experience for other teams trying to work with your services, you might focus on architecture diagrams and API documentation. If your target audience is limited internally, i.e., to your own team, you might emphasize READMEs, installation guides, and screenshots. Your approach, then, may be more focused on how you can make your own team more productive and capture related information.
Having clarity on your reasons for putting together technical documentation will help you define your goals and subsequently build a realistic strategy to achieve them.
Identify what needs to be documented
Take stock of your existing code as well as the team’s workflows and business processes. Only when you are aware of what exists can you decide if and how you want to document it.
Common types of internal documentation that software development teams need are:
Architecture diagrams
Runbooks
Deployment checklists
Technical design documents
API documentation
Decision-making documentation that explains why a certain decision was made and what its subsequent impact was.
External-facing documentation for other stakeholders to understand specific things about the service. These can be truly external stakeholders or belonging to other teams within the organization.
Use this list to get started but feel free to add anything else that is relevant and needs to be preserved for the long term.
Decide how to store it
In addition to the motivations for it, it is important to figure out where you want to put your documentation. Put simply, different things can live in different places. For example, the installation guides could be your README files, but the runbooks might live in Confluence, while your API documentation lives someplace else altogether. Where you decide to store the various components ultimately depends on what you are trying to achieve.
That being said, no matter the type of documentation, it must be standardized. For example, as an organization, if you decide to store your installation guides in your README files under a particular section, then every single one of them must be stored in that way without exception.
There are multiple benefits to this practice, including the simple fact that this will make your documentation easy to find. No longer having to deal with unnecessarily maze-like systems, teams will also have an easier time onboarding new members. The latter need not reach out to older team members every time they are looking for something. So, deciding on the tooling for each type of documentation is a necessary step in the process.
Consider hiring a technical writer
Organizations, especially larger ones, can also consider hiring somebody to build a system and maintain documentation full-time. This is a fairly common practice. Former librarians or technical writing experts are particularly adept at organizing knowledge bases. They are able to think about how documentation must be organized once collated such that it is easy to find.
So hiring somebody full-time to manage this aspect of the software development process can be valuable for larger organizations that may not have the bandwidth to handle the complexity of their documentation tools. At the end of the day, the knowledge that has been generated internally over many years is of tremendous value.
Define templates
Once you know which types of documentation you have and where each is going to be kept, it is time to define templates. Every single type of documentation should have a template.
For example, every runbook should have a standard template that people can simply fork and start using, whether it is in Confluence or GitHub. A runbook might include things like how to use it, when the runbook is relevant, a checklist of items, steps to take to remediate, and people to message about that. Technical spec documentation templates, on the other hand, might specify the problem you are trying to solve, a link to the product specification, technical design questions, design decisions, a project plan, and a link to the JIRA project.
Defining templates for each documentation type makes knowledge management easier. It simplifies the process of categorizing items and building a knowledge base. Searching for items is no longer a hassle either. It is important to make documentation easy to access and use because if nobody is using it, there is no point in investing time in documenting various aspects of the development process. Writing templates is also a great way of making sure that there is consistency in the way that teams work and build services.
Keep templatization in mind when deciding on the tools you will use. Choosing a tool that has a concept of templates makes it easy to write them. Confluence, Google Docs, and Notion all fall under this category, allowing people to select the template they need and begin using it immediately.
Keep the reader in mind
Think about internal documentation (internal docs) the same way you think about external documentation. So assume your reader doesn't know anything. Including specific commands and screenshots throughout, as well as anything else you think will help simplify the explanation for the reader and make it easy to understand.
Too often, for somebody who already knows a process inside out, it is easy to skip details or not offer thorough explanations. This does not help the reader, who, it is best to assume, has zero knowledge about the subject. Clarity is key, and if that means that you need to go into great detail in order to explain something, then it is worth putting in that effort.
Some team members will leave the company and new ones will join. The documentation needs to be such that it can be understood by itself in case there is no one to offer an explanation a few years down the line. And it is only when it is comprehensible can the information be used.
Be open to change
As time passes, your team may start doing certain things differently. Workflows evolve, as does the product you are building. For this reason, it is useful to think of documentation not only as a means of preservation and knowledge dissemination but also as something that is reflective of your team, its work, and how it does this work. Being open to the idea of modifying documentation is essential to ensure that it is relevant and up-to-date. In practical terms, this can look like using dynamic documents to record everything in.
How can Cortex help you?
Cortex’s service catalog is a one-stop destination for all your microservices-related needs. It offers your team a comprehensive view of the existing services in your architecture, as well as any related documentation. This means that employees can know exactly where to look if they need information about a specific microservice. As a result, the service catalog is a useful tool to organize and maintain your documentation.
