Code documentation has never been considered fun. Maybe it’s time we changed that.
Documenting your code is often seen as an arduous, yet necessary chore. For many developers, this process is time-consuming and brain-draining – which is the complete opposite of how it’s supposed to be. A core part of the documentation process – creating visuals and diagrams — might be the key to better developer communication.
Creating diagrams should be a dynamic, helpful and fun learning experience. We should look at diagrams as amazing visual communication tools that help us save time, anticipate potential problems in our code and collaborate with colleagues across professions.
So what’s holding us back? For one thing, the landscape of diagramming tools and platforms is crowded with solutions that don’t quite fit our needs. Most software prioritizes functionality or presentation – but rarely both.
Diagramming your code should be more like Google Docs. Colleagues should be able to work on the same diagrams in real time – without worrying about duplicates or outdated versions. We should be able to comment, suggest and chat as we build out sequences and flow charts and user journey diagrams. Dynamic, well-kept diagrams can make our code cleaner, replace back-and-forth emails and keep entire teams aligned, even as they work remotely.
If we can find the right tools and workflows, there’s even potential for diagrams to become the chief form of communication in the workplace, for everyone from coders to marketers to lawyers.
Realizing the power of diagrams for documentation
Years ago, I was working on campaign management logic for an e-commerce company. This logic was complex, and every time I started working on it I had to go through the code to explain it to various parties. This got old, quick.
That’s when it hit me: why don’t I make a flowchart to outline the steps?
It worked. Instead of running through all of the code, I could simply pull up my flowchart and everyone, technical or not, would be able to understand. It was a control system for discussion.
I realized that the first time I’d set up states in a payment flow, I’d over-engineered something that was unreasonably complex. If I’d built the flowchart first, I would’ve noticed it before I got too far.
That’s the beauty of diagrams; they provide a blueprint that allows you to understand the whole of what you’re building before you make progress.
What’s wrong with the way we’re currently building visuals?
Understanding the importance of effective diagrams is one thing. Actually following through and creating them is another.
Generally speaking, developers don’t have the right tools to quickly and efficiently create visuals for their code. Three problems stand out:
Time: The process takes too long.
Dev teams are spending too long trying to build diagrams and communicate their message, which eliminates how much time they have to actually write good code and move projects forward.
Creating designs in Powerpoint or some other tool feels clumsy. Very few enjoy drawing arrows and boxes with their mouse. Updating diagrams for constant changes becomes a time thief.
Version Control: Diagrams and code are out of sync.
Perhaps you build a diagram that exists in different places — in your diagramming tool, as a screenshot in the code itself or in a separate presentation. What happens when you make a change to one version of that diagram? Suddenly the other versions are out of date; those static screenshots don’t update on their own. It becomes harder to trust your documentation, and now you have to spend time evaluating the documentation versus your original code (defeating the purpose of documentation in the first place).
Presentation: We’re missing the Goldilocks zone.
We haven’t struck a balance between visually pleasing diagrams and effectively communicating ones. Many of us have encountered a “fluff diagram”: something that looks great, but dodges the core issues and takes far too long to create. If your diagram isn’t robust enough, it won’t be effective for communication — especially when you’re working across departments.
What could a future with better diagramming tools look like?
The next generation of diagramming platforms has to address these three core problems. Once we get there, developers will achieve better quality in their documentation. But what does that actually look like?
True connectivity between diagrams and code
Developers need a single source of truth for their diagrams: a singular vault that eliminates stress over version control. We should be able to make a change to a diagram in one spot and have it automatically update everywhere else it appears — in the code and elsewhere.
More meaningful collaboration
Let’s take it back to the Google Docs example. Diagrams should be a dynamic, web-based workspace where teams can collaborate synchronously or leave comments for each other in an async workflow — which would be especially helpful with remote workforces that are more spread out. Certain team members could be given different permissions, allowing them to edit and render only the parts of the diagram they’re working on.
By using a diagram, dev teams can have a common view of their workflows, which decreases the risk of misunderstanding and makes it easy to spot errors in a group when jointly validating a design.
Documentation is actually….fun!
It’s scientifically proven; fun is essential for a great workplace. We do better work when we’re enjoying ourselves, and documentation should contribute to the good vibes.
Building diagrams should feel like magic, not a maddening game of click-and-drag with your mouse. We should be proud of the visuals we create because they’re crystal clear, look great and don’t take forever to make.
It doesn’t stop with developers: the case for visual communication
As you know, documenting processes isn’t exclusive to developers. Diagrams can provide a common language between professions as they communicate business processes.
Theoretically, anyone that needs to communicate ideas should be able to do so through a robust yet simple-to-make diagram. Long emails can be replaced with visuals. Handbooks and how-to guides can be trimmed down, with charts replacing large chunks of text.
Workplaces will begin speaking in diagrams — and anyone from business development to HR to engineering can join in the fun. People will collaborate from different locations, and colleagues will be able to build together.
We live in a visual world. The future of work should be visual, too.