Software Documentation: A Recipe for Success

As we discovered in The Why and How of Software Documentation it is exceedingly important to document software development. We also discussed where is the best place to document and continuously iterate it. But who is responsible for the documentation?

I guarantee that if you asked varying roles in the software industry, the response will differ each time.

Types of documentation

First and foremost, it’s important to identify the different types of documentation that form part of a software project. Let’s split them up into two categories:

• the codebase and;
• the supporting documentation.

Theoretically speaking, as lines of code are written, there is a line of thought that says it’s already documented, because “it’s right there in the code!” I have heard this line many times. In some circumstances, the code itself is enough information for the developer to derive what is happening. Other times, it falls short of what is needed.

The function or script may have been written in a certain way to ensure something doesn’t break in another part of the application. Without properly commented code there is no way another developer will know that it must work in that way.

One of the core elements of the agile methodology is that it is constantly learning, without needing to start from the beginning each time. In documenting the research, the trials and the successes, it means that the knowledge of not just how the software works but presenting the discovery as to why it operates the way it has been implemented, rounds out the understanding.

Project management tools such as Jira exist in the same suite as Confluence where they link together seamlessly, therefore, promoting consistent documentation. Yet, even with seamless integrations between management and context, the lack of documentation for many software applications is broadly felt by the industry.

Additionally, an application is not just made up of software. It is the collaboration of ideas and execution from product owners, designers and developers.

Product Owners, or the main business stakeholders, have an important contribution to the software documentation. They are able to create a back story, set the scene and present examples for the problem the software is aiming to solve. I have seen a brilliant example of this from a recent customer of ours at WorkingMouse. The brilliant articulation of their business case, their user groups and their plan for the future of the application meant that everyone working on this project was aligned on the objectives.

This documentation not only provided us with a great understanding of the project from the beginning, but when we brought more developers into the team, the onboarding rate was much faster than we anticipated.

Who is responsible for software documentation?

As someone who has worked with a range of different development teams, I have never really come across a valid reason for why this responsibility seems to bounce around from team member to team member.

As I’m not a software engineer, and I feel like I have said the word “code” too many times already, I am going to put this situation into a more relatable scenario. One of my passions is cooking and one of my hobbies is pouring over cookbooks. Something I noticed about the recipes that I tend to lean towards, for inspiration or to follow, are the ones that have a little blurb at the top of them written by the author chef.

I know this is a strange comparison between technical documentation and cooking but stay with me!

Each time I read a blurb about a recipe, I am immediately oriented with the style I need to be cooking in and the kinds of results I should see in the end. Therefore, when I get into cooking the recipe that contextual information is subconsciously guiding my actions and (hopefully!) I get the results intended. Something particularly interesting with this approach is the ability for someone who is not an avid cook to read the blurb and then be able to create their own understanding of what they might eat (or attempt to cook!).

Why is documentation important?

We can think about this style of information transfer between an expert and an enthusiast similar to a software engineer and a product owner. The software engineer develops the recipe for the product owner to read, but the steps alone don’t paint a picture of what the recipe is for or what it is intended to create in the end. Hence, the blurb.

The other style of knowledge transfer we need to consider here is the software engineer who created the application, to the software developer who is going to maintain or iterate on it. Most of the time you’re not documenting for yourself, you’re documenting for Developer Z that enters the project 12 months later with no background context. What do they need to know to succeed in their role?

To follow our kitchen metaphor, think of an executive chef entrusting their carefully curated recipes to their underling chefs. It is the trust that the kitchen staff will be able to reproduce that recipe time and time again to the standard the executive chef first created it.

Honestly, this just sounds like a very normal part of #cheflife but as someone who has worked with chefs, I can tell you that they receive those recipes with notes and context and a showcase of how to cook them. It is this careful transfer of knowledge that allows the chefs to succeed.

So, what can we draw from this metaphor? This brings me back to one of the first points I raised in this piece, the fact that the responsibility of software documentation is not agreed upon. The responsibility of creating the documentation lies with the creator.

Document now, benefit later

Have you ever looked at something, like a billboard or poster and wondered, “why is that designed in that way?” I can absolutely tell you now, that although the design may seem simple, there would have been hours dedicated specifically to it. During those hours, there would have been mountains of research undertaken and many decisions made. The same goes for the design of an application. Product designers commit hours to understand the user and designing a system that will suit them perfectly. This user understanding should be documented also for the same reasons as I have fleshed out above. It promotes consistency, and continuity of the application.

It is a part of WorkingMouse’s Way of Working that we allocate time to document everything throughout a project. It is also considered ready for completion when everything has been documented succinctly so another developer, a non-technical person and even the product owner can review and understand what has been written.