Technical Documentation for Agile Development Teams
Development teams have been growing worldwide over the past decade. The amount of information shared within large companies can feel overwhelming at times and the act of sharing information is not as simple as it seems. In fact, many books on the importance of good documentation have since been published.
In many companies without a clear procedure in place, developers often spend a significant portion of their time tracing information, researching payloads, and even holding meetings to arrange information.
Consider the following example: a colleague is transferred to another team and we no longer have their time or knowledge at our disposal. In situations like these, the importance of proper documentation is paramount. It can help reduce the time spent on executing processes and enable us to quickly address bugs or make fixes in case of emergencies. Additionally, documentation serves as a valuable asset for sharing the steps to implement a new process or install a new library.
Remote Open Source contributors have been creating solid documentation for a long time, setting a standard for the industry to follow.
Organizing Documents at SSENSE
At SSENSE, we encourage each other to prepare documents that are easy to read and maintain, with the goal of sustaining and increasing productivity in a rapidly changing environment.
Over the years, our teams have learned and discovered various methods to effectively organize and manage important pieces of information. Let’s delve deeper into how documents can be organized and divided to help readers easily find the important parts of the information.
Is Documentation Only Required for Remote Work?
Proper documentation is essential in all work settings. Whether remote, in-office or hybrid, documents can facilitate knowledge sharing without the overhead of constant interruptions.
The importance of clear documentation has been championed in the Open Source communities. Well-articulated ideas in documentation can help reduce the time spent in vague meetings, serving as a stepping stone for concise discussions and decision-making.
Types of Documentation
At SSENSE, we have various types of documents serving different purposes. Purpose is crucial as it guides our writing approach from inception.
Depending on the type of document, the details will vary. For instance, if you’re writing about how two applications interact, you will focus on the payloads and events. If you’re documenting a library that will be used across the company, you will concentrate on the set-up steps and example usage.
Let’s look at some concrete examples of documentation types.
Onboarding Documentation
This type of documentation is for new team members or those coming from different teams. It provides a general overview of the team, its mission, past achievements, and an index to our current research, agreements, or discussions.
It is also a good place to add resources that will help newcomers familiarize themselves with the technologies in use.
Conceptual Documentation
Conceptual documents provide an overview of how your systems interact or work without delving into technical details. They include BPMN and may contain diagrams explaining interactions between services or reasons for exchanging information.
Consider this a type of documentation that should be shared with stakeholders or non-tech colleagues. The simpler and more concise it is, the more likely they are to read the entire document.
Procedural Documentation
This type of documentation is meant to display steps to follow when working on installing a project, setting up an API, or runbooks for running specific scripts to address needs.
When creating this documentation, you have to organize your thoughts ensuring that the outcome is reproducible and without side effects. If that is not possible, you should provide users with warnings or redirect them to related reading material.
Organizing Documentation
Users Typically Look for Specific Information
When reading a lengthy piece of information, readers often search for keywords or useful subtitles in the index. This is especially true if they are in a hurry, trying to solve a bug, or presenting the topic to an audience.
So it’s important to understand that there are two types of audiences:
The first type includes those who have a specific goal and just want to grasp the main idea or the most important conclusions from your text.
The second type enjoys lengthy reads and delving into the details. For these readers, you also need to provide more context around the reasons behind a decision or idea.
Working with Templates
Once you have found a way to effectively organize your documents, consider sharing them as templates. This helps with standardizing the organization of information across teams.
With templates, you can save time and effort by not having to reinvent the wheel each time you need to write something for your team.
Create as many templates as possible and update them according to your needs. Avoid struggling to create the perfect first template; having a first version is better than having nothing at all. Over time, you’ll uncover what else can be useful and you can make the necessary modifications as you go.
Simplicity Is Key
When preparing documents, it’s tempting to include a lot of content, assuming that the user will read every point as if they’re reading a book. This usually happens because we don’t consider when we’ll need to refer back to the document. Creating simple documents that cover the most essential points is key. Of course, this depends on the type of document we’re creating. If we need to explain why we’re taking each step, it might make more sense to create a supporting document, keeping the first one as a procedural document.
Enhancing Your Documents
Like any other document that aims to organize information, there are elements that highlight the most important topics. Knowing that users will seek out the most critical points in our document, we should assist them in getting straight to the point.
You can add as many elements as you want to ensure proper organization. But here are the ones we’ve found to provide a more seamless reading experience.
Titles and Subtitles
Titles and subtitles are crucial elements that guide the reader toward better comprehension of your text. They attract attention to the subject matter and should be concise while accurately representing the content that follows.
Certain tools use titles and subtitles to create a “Table of Contents” with links that directly link to specific sections, providing a concise navigation map of your narrative.
Code Snippets
Since we’re talking about technical documents, this is crucial information to present.
At SSENSE, we pay attention to even the smallest details. Specifically, we follow these two steps:
- Use meaningful code snippets
- If the tool permits, add syntax highlighting
Let’s delve deeper into these two specifics.
Meaningful Pieces of Code
Let’s suppose we’re discussing AWS Step Functions and their configuration. If we display a complete YAML file, the reader may feel inclined to skip this code piece, deeming it unhelpful. However, if we extract the 5 to 10 most useful lines of code, this simplifies the reading experience.
Also, leverage the comment feature according to the coding language. This allows you to insert symbols like …, indicating that there’s more code not currently relevant to the topic at hand.
Syntax Highlighting
If you simply copy and paste code, there’s a high chance that the tool will default to displaying it as a combination of gray characters. This is fine for common text. However, there’s a reason why most developers, or at least a large majority, use a theme in their code editor. They want to highlight the main keywords according to the language or identify the principal pieces and core functions, classes, and variables to make them easier to read in the future.
Images & Recordings
Even if you are writing technical documents, it can be useful to include some images. In technical documents, images will likely be diagrams exported as PNGs or screenshots from the product website or application.
If you’re adding screenshots, make sure to always use arrows and circles to direct the user’s attention to the feature you want them to focus on.
Remember, not only technical people read your documents. It might be your Product Manager in a rush, looking for that specific design bug that you reported last week.
Also, if you’re showing a flow that requires specific steps to reproduce, it might be better to record the steps. This saves space in your document. An image is worth a thousand words, but a video is worth a thousand images.
Whether you’re using an image or a video, remember to ALWAYS respect privacy. Never use any sensitive customer data in them. Screen capture or recording tools come with a blur feature so make use of it to ensure your recordings are safe to display to a wider audience.
Diagrams
Diagrams are excellent ways to display processes, especially as your service or company grows and you need to explain different flows. They are also ideal for presentations to non-tech individuals, provided they are simple and easy to understand.
When creating diagrams, remember not to combine too many colors. If you use more than one, always use the same color for the same type of process or for grouping some of the endpoints or resources of the diagram.
To show connections between the different resources, you can use arrows to indicate how the information is transferred between them. Make sure to always use arrows in the correct direction, and consider adding text to the arrows with verbs to indicate what’s happening in parallel (e.g. sends, executes, triggers).
At SSENSE, we employ diagrams to simplify and segment our complex processes into understandable blocks of information for everyone in the company. They also serve as our preliminary draft before we enhance or create any processes.
Tooling
Tools are an essential aspect of any business. With a plethora of options available, both free and paid, it’s important to standardize the tools you use.
Here are some of the tools we use at SSENSE.
Paid Tools
Google Docs
Google Docs is a popular option. Our teams use Google Docs to write first drafts of documents and guidelines related to tech news. It’s a good option for groups that want to collaborate simultaneously on the same document.
LucidChart
Lucidchart is our go-to tool for creating diagrams, thanks to its intuitive what-you-see-is-what-you-get interface. It also features AWS service-related blocks, making it an ideal tool for our Software Architects, DevOps, and Developers to visualize and share their ideas.
Lucidchart supports the creation of various types of diagrams. You can choose from multiple components and resource representations in their panel.
Open Source Tools
Backstage
Backstage is an Open Source platform for creating a developer portal. This is more than just documentation, it’s a space where teams can display the ownership of their projects and how they are connected to others within the company.
Backstage includes BackStage TechDocs which leverages the power of Markdown to write documents in the portal. These can be reviewed through Pull Requests before being added to the documentation.
To know more about Backstage and how we chose it, take a look at our previous article.
Mermaid
Mermaid allows you to create diagrams with code. If you are a developer or manage a group of developers, this can be a convenient way to create diagrams that can be updated frequently over time. It is supported by various documentation tools on the market. You can generate state, flowchart, C4, timelines, sequence, and other types of diagrams.
The Power of Effective Documentation
We ultimately all work in a knowledge-based industry and documentation plays an important role in capturing information and sharing said knowledge within our companies.
From speeding up the onboarding process to expediting requirements gathering for a new project, having effective documentation as part of your development lifecycle is a must.
While the exact artifacts will vary depending on your context, it’s important to focus on identifying the audience and disseminate both the good practices and tools to help developers and product teams collaborate on creating and maintaining documentation.
References
- Docs for Developers: An Engineer’s Field Guide to Technical Writing. Jared Bhatti, Zachary Sarah Corleissen (Contributor), Jen Lambourne (Contributor), David Núñez (Contributor), Heidi Waterhouse (Contributor). 2021
Editorial reviews by Catherine Heim, Luba Mikhnovsky & Mario Bittencourt.
Want to work with us? Click here to see all open positions at SSENSE!
