Write the Docs – The Legend of Documentation: A markdown to the past by Filipe Mendes

Filipe Mendes is a software developer at ITV in London, but he actually works for a company called Candyspace. He gave a talk at Write the Docs Vilnius on how he promoted the value of documentation within his software development team, and implemented some useful documentation processes. 

The Legend of Documentation: A Markdown to the Past

Developer documentation

Among developer communities, technical documentation has not been spoken about much and the reputation of documentation among developers is well-known. Developers don't see the point of writing docs when they could write the next Facebook, and yet we've all suffered from a lack of available information when we needed it.

"The resistance to documentation among developers is well known and needs no emphasis" – D. Herbsleb & D. Moitra

Filipe told the story of his team, which was made up three men and then he joined as the fourth member. At the time, their only documentation was a README file and this led to some major issues during his onboarding process. 

He went on to use or develop some useful forms of documentation including:

• README
• Developer wiki
• Request for Comments
• Postmortem
• Pull request descriptions

Filipe discusses these different types of documentation in more depth. Filipe describes in detail the four problems he encountered because of a lack of documentation within the team. 

Problem 1: Lack of knowledge about the app

The team used JIRA to track their issues, and early on in the job he was asked to look at some tickets. Unfortunately, there was a lack of documentation on the code he was tasked to help with. This meant that Filipe needed his tech lead to guide him through all the steps, wasting time that could have been better spent helping customers or developing new features. 

Throughout this process, Filipe made extensive notes, and he realized his notes might be helpful for someone else later on. They created a developer wiki so Filipe could share his documentation. It contained information on their application architecture, as well as URLS needed for third party integrations. 

Filipe himself had to revisit his notes several times, and the rest of the team said that his documentation was useful for them. Documentation requires doing work for someone else, and it is an investment in the future that requires sacrificing valuable time in the present. 

Problem 2: No process for tech planning

Sometimes Filipe would be trying to fix a problem in the software, and he discovered that other people would get defensive about the time they had spent working on code. This led to bottlenecks and it seemed like it would have been better to collaborate at the beginning of the design process. 

Filipe spent some time working on a solution called Request for Comments, which was a form of documentation. He created an issue asking for feedback from the team for a solution he was planning to develop. 

In the past, when they planned to develop a feature, they asked for a code review after development and then merged the feature. The Request for Comments meant that the review happened before worked started on a feature, in order to ensure everyone could give their feedback. Request for Comments would have made previous tasks much easier.

Implementation without Request for Comments

Implementation with Request for Comments

An old team member rejoined and was resistant to using the Request for Comments, since he preferred to discuss new features face-to-face. So the team adapted by adding a meeting into the process, but kept the documentation in place.

Problem 3: Lack of information about past incidents

There were many things that had happened in the software development process that Filipe wasn't really sure about. In teams that change even infrequently, information gets lost and lessons are forgotten. People ended up with no idea why certain tools had been replaced, or introduced in the first place. 

Questions to ask about a software system

This lack of information created big problems. For example, they might have been wasting time working on solutions that had already been implemented. Clients also expected them to know the answers to their questions. 

Filipe started learning about postmortems, which are an analysis of problems and bugs after they have occurred. The postmortem clarifies and documents what happened. It can be shared with management or the client, and future colleagues can learn from past mistakes. By implementing postmortems as part of the new process, this ensured that they would have the information they needed in the future. 

Problem 4: Pull requests with no description

Then the encyclopaedia of the team left, who was one of the original founding members. This led to a new problem relating to pull requests in the codebase. The team realized that having no descriptions on their pull requests was now a problem during the reskin of their app. 

A simple change can have a big UI impact for users in terms of what they see, so they needed to know why various changes had been made to the code. This is a big reason why adding more information to comments on pull requests helps later down the line. 

Why documentation is so important

Having documentation to refer to later sped up the onboarding process for new team members. 

"We do a great job if our team is not dependant on us. I feel proud if I leave and everything is still working great without me," says Filipe. "Documentation is for the team/project, not individuals."

He recommends slowly introducing documentation to your team, and showing the value of documentation first before asking people to invest effort into producing it.

You can follow Filipe on Twitter or connect with him on LinkedIn. Consider reading our full write-up of Write the Docs Vilnius. 

Our very own knowledge base software KnowledgeOwl can help you create delightful documentation for your users. Take it for a free spin now.