Here at Rootstrap, we help our clients reach their business goals by developing high-quality, performant, and scalable software solutions. To achieve this, our team continuously focuses on improving all aspects of our processes, through several initiatives across all company departments.
In this article, we will examine why documentation is vital for the software development cycle.
Why is Documentation so Vital?
You may be wondering what exactly the benefits of documenting are. Let me tell you a brief story. In March 2020, we started working with a client on a very exciting project. However, the whole team then had to switch to remote work, as a result of COVID-19. Therefore, we had to focus on maintaining fluent communication among our frontend and backend developers. To achieve this, the backend team started to document the API features and the available deliverables right away with different tools. Doing this helped to maintain the team's velocity, reduce synchronization time between devs, and kept everyone up to date on each other's work.
Many features require backend work to be done first so that frontend devs can integrate their mocked code with the API afterward. This now implies that backend devs not only have to code and test but also add documentation on each newly released feature. By the time a frontend dev starts working with any API endpoint, they already have a detailed description of returned objects. They will also be aware of whether authentication is needed or not and will see any error messages that may arise based on different use case scenarios.
Later on in the project, the client hired a content manager who was tasked with uploading new episodes and exclusive content to the platform. As a result, the team started developing documentation for the content manager to understand all the logic behind the administration site, for example, how to upload new content, schedule episode releases, and so on. These documents were linked on the administration's dashboard site itself for easy access.
Documentation Tools
Here are some of the tools we use everyday to document project deliverables.
Oracle Apiary
Oracle Apiary is an API design stack we use to describe all endpoints using [.c-inline-code]API Blueprint[.c-inline-code], a really cool description language based on Markdown. It allows for specifying actions, declaring objects, and data structures. The online editor provides an automatic validation which helps developers to keep documents consistent. Here is a brief syntax example that is taken from our open-source Rails API Template:
Postman
Postman is an amazing API client we use locally or with our testing environments so everyone on the team is able to inspect endpoint responses and debug. This is especially useful for frontend developers since it enables them to quickly get responses based on the request attributes. Furthermore, the environment can be easily switched in order to make a request (e.g. [.c-inline-code]staging[.c-inline-code], [.c-inline-code]production[.c-inline-code], and so on). Postman helps the team to better understand how the API works.
Repository READMEs
READMEs is a powerful yet simple way to communicate to your team developers about important project settings. Here is an example from our Rails API Template. There are plenty of aspects that may be included, but it's important that developers take ownership of this initiative and update this file whenever is needed. Besides keeping the README file updated on setting up the project for development and listing used Ruby gems, we also started listing all the environment variables names needed for the different environments to work correctly.
ActiveAdmin Dashboard
ActiveAdmin is a popular administration framework for Ruby on Rails applications. This plugin makes implementing interfaces for managing content simple. Not only does it offer an extensible way to customize all different sections, but it also provides the user with a dashboard. So, as mentioned before about documenting different aspects of the administration site, we added these links on a new Documentation panel.
Notion
Notion is an all-in-one platform that connects all the company areas: from product and design to engineering. It allows us to share knowledge about projects, internal initiatives and so much more. In this specific project, designers portrayed content guidelines so that both web and mobile versions keep visual consistency. As an example, designers detailed some image upload specifications. By doing this, the content manager is able to adapt content so that it fits perfectly on the site. This is just one example of the different capabilities that this tool offers.
Conclusions
I strongly believe that good coding practices should be accompanied by high-quality documentation throughout the development cycle. It helps new team members get onboarded faster and understand the project from the get-go. It also helps designers understand content architecture so they can reason with it. Additionally, it helps clients to communicate with stakeholders about product capabilities. One more advantage, it can also help developers be more aware of the system as a whole. In conclusion, documenting increases product quality and reduces development time in the long run.
