Why developers should use diagrams as core documentation

I’m going to let you in on a secret… developers hate writing documentation. Okay, maybe that’s not a secret. We grudgingly accept the need for documentation as part of our core deliverables. Though we may complain about documentation getting in the way of “real work,” we do understand the fundamental need for documentation (especially when we are the ones looking for additional information on a part of the system new to us). Proper time estimates for resolving issues should include adequate time for documentation to promote long-term application health and sustainability.

A frequently neglected area of developer documentation is diagrams. This neglect happens for many reasons. Useful diagrams take more time to create than a few sentences. Diagrams may be seen as more of a project management or business analyst function. Even something as simple as lack of consensus on the best tools to use for creating, modifying, and sharing diagrams could discourage developers from creating them.

So why should a developer care about diagrams and consider them as living documents they are responsible for?

Team expansion, contraction, and restructuring

Every developer has been the new member of the team, usually multiple times, during their career. Those first days as the newbie are normally a whirlwind of getting appropriate network and tool access, setting up a working development environment, and reading through (potentially) copious application documentation. While the majority of effort is often devoted to written documentation, wouldn’t it be great if good visual documentation were available?

Speaking from experience, the answer is a resounding YES!!! Whether they are system architectures, package layouts, ER diagrams, or the myriad of other potential diagram points in a system, having visual sources of record available helps new team members get up to speed quickly.

 

In modern Agile development environments, enabling developers to become knowledgeable and productive faster is key to successful projects. No longer do we have the luxury of letting new team members ease into the pool over a couple of months like we did under older Waterfall models. Constantly evolving diagrams are a necessity in these environments.

At the other end of the pipeline, developers will leave projects. Whether this is due to moving to another team, restructuring the team when the application goes to production, or exploring other opportunities, team composition will fluctuate. Good documentation will guarantee that system knowledge is not lost.

Dedication to diagrams will shine here. In many instances, it is easier to convey state through visual media than it is to rely on written documentation. This is especially important because there may be no one to address questions to as team members depart. Those who are left behind will be thankful for your efforts in maintaining living diagrams.

Mitigation of PM and stakeholder requests

This next part falls into the category of managing your manager. In the eyes of most developers, the realm of management is meetings… lots and lots of meetings. And presentation slides are the bread and butter of meetings.

Sadly, we are not exempt from this part of application management. In addition to being pulled into meetings, hindering what developers see as “real work,” we are frequently tasked with coming up with slides (or at the least material to be included in slides) for meetings. The more well known you become for your development experience and architectural insights, the greater the requests for your input become.

Maintaining good diagrams will ease your burden. You will be able to direct PMs and other stakeholders to diagrams instead of having to put something together at the last minute (as many of these requests are). Depending on the detail put into your diagrams, you may be able to avoid attending many meetings entirely. Given advanced diagramming tools that are available, your diagrams can often tell a complete story with little to no further input on your part.

A secondary consideration of diagrams for developers is their persuasive role. It becomes much easier to convince management of certain directions and decisions, such as a move to AWS, inclusion of a Redis cluster, or feasibility of requested features with good diagrams to back up your arguments. This is especially true with detailed diagrams that can show historical progression side by side with predicted results and proposed architectures. Using living diagrams as part of your justifications for decisions will help you reach consensus with management quicker.

In conclusion

These are only a few reasons why producing and maintaining good diagrams are important to you as a developer. You may have noticed I didn’t use the term “visual aid” when talking about diagrams. Though this term is often used when referring to diagrams, it sets a bad context. The term generally brings to mind something that cannot stand on its own, an excisable part that is not necessary to the whole. You should never think of your developer diagrams in that way. Diagrams are vital aspects of your core documentation. They should be strong enough to stand on their own, telling complete and compelling stories.