Posted on January 25, 2022
This article will take about 4 minutes to read.
Documentation is a relevant topic in the software industry, especially when projects or products start growth and teams' structure becomes more distant or distributed. This article aims to give four tips about documentation and make this process natural. Before starting, I'll assume that your team already see value in the documentation.
Before starting to document is essential to understand what your team needs to write down. Think about which information is relevant for every context. You need to look the big picture and explore that to do it. What truly matters for the team's engineers? And for Product Managers? Product Designers? Each people see different levels of relevance in each piece of information.
For me, the best way to understand this level of relevance is to talk with everybody in the same room and point out the highest topics, for example:
Are your team working on features for mobile apps? Consider documenting in what app version the features were launched, and this could be relevant for Product Managers (these will use it on their analysis) and for Software Engineers (who may use it on monitoring). Another one, is there some remote configuration or feature toggle? Consider adding it in the documentation to have easy and centralized access.
After figuring out those topics, I'd recommend creating a template. This task is part of the next topic. The process should be easy to keep people involved, and this is key.
Every person in your team should be able to create or edit documentation in just a few clicks. No matter how technical this person is, consider using tools that are visual and easy to use, markdown is cool 😎, and I, as a former Software Engineer, agree with that.
Still, I'm not sure if a Product Manager/Designer would like to open iTerm2, clone a repository, and commit to updating something.
Make sure that all docs are on people's faces. That will act as a reminder to use it (then they will find points to get better) and document more. Suppose your team is starting to create docs. In that case, I'd recommend notifying everybody when a new doc is on the air. In my experience, it is a good idea to show the gear working.
Another suggestion is to create your docs in a centralized place with easy access. Ideally, that place should provide friendly tools like a good search engine, structured pages/indexes, related content, and history.
After understanding more about team necessities, setting a place to document, starting to create/update docs, the work is almost done. In general, teams that need documentation are part of a dynamic structure, so things around can change in a few months. You may need to update the documentation vision that was created.
My last tip is about getting back to the subject, putting people together again, and thinking about what should be updated. Do we need a new template? Will some integration help us? Those are an example of questions that will drive new updates. And, after some months, do it again 🙃.
Liked this content? Any feedback? Feel free to send me a DM on Twitter