diagrams as documentation

Why developers should use diagrams as core documentation

Rodney West

Reading time: about 4 min

Topics:

  • Diagramming
  • IT and Engineering

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.

 

Onboard your software engineers with Lucidchart

Learn how

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.

Start visualizing your technical systems today.

Learn how

About the author

Isos Technology is an Atlassian Solution Partner providing enterprise solutions and coaching to private and public sector organizations. As a senior consultant at Isos Technology, Rodney West enjoys the interaction between anthropology and software engineering found in consulting engagements. Connect with him on Twitter and LinkedIn. 

About Lucidchart

Lucidchart, a cloud-based intelligent diagramming application, is a core component of Lucid Software's Visual Collaboration Suite. This intuitive, cloud-based solution empowers teams to collaborate in real-time to build flowcharts, mockups, UML diagrams, customer journey maps, and more. Lucidchart propels teams forward to build the future faster. Lucid is proud to serve top businesses around the world, including customers such as Google, GE, and NBC Universal, and 99% of the Fortune 500. Lucid partners with industry leaders, including Google, Atlassian, and Microsoft. Since its founding, Lucid has received numerous awards for its products, business, and workplace culture. For more information, visit lucidchart.com.

Bring your bright ideas to life.

Sign up free

or continue with

Sign in with GoogleSign inSign in with MicrosoftSign inSign in with SlackSign in

By registering, you agree to our Terms of Service and you acknowledge that you have read and understand our Privacy Policy.

Get started

  • Pricing
  • Individual
  • Team
  • Enterprise
  • Contact sales
PrivacyLegal

© 2024 Lucid Software Inc.