<Understanding Why Many Software Engineers Avoid Documentation>
Written on
In any organization, whether it's a small startup or a large corporation, there often exists a significant lack of effective documentation for services or projects. This deficiency can hinder various organizational functions, from team discussions to onboarding new employees who need to familiarize themselves with system structures and interactions.
Despite widespread acknowledgment of this issue, the question remains: why does it persist in today's environment?
The Significance of Documentation
Meetings
If you've participated in discussions about new projects and how they fit within your existing codebase, you're likely aware of the multitude of ideas and solutions that are debated. The complexity of these discussions often grows with the number of attendees.
Each suggested solution comes with its own set of advantages and disadvantages, all of which are considered during the meeting. After such discussions, as you return to your regular tasks—like coding a feature—do you truly believe you'll remember all the proposals, the pros and cons, and the reasons for decisions made? The reality is, you probably won't.
Acknowledging this limitation isn't a weakness; rather, it's a strength that can lead you to mitigate its effects. To avoid wasting valuable time and resources, documenting the meeting is essential.
Taking notes during or immediately after the meeting is a great way to ensure that your colleagues can reference what was discussed. Aim to capture the key points, the various proposals, their respective pros and cons, the decisions made, and the action items.
Revisiting Decisions
This section has a philosophical tone, but it holds true.
As your business evolves and new requirements emerge, decisions made a year prior may adversely affect these developments. At that point, justifying those choices to upper management can be challenging—especially if you can't recall the context behind them.
Having documentation from your meetings can clarify the rationale behind past decisions, whether they were made due to stringent deadlines or other factors.
Idea Discussions
In traditional office settings, engineers often brainstorm ideas on whiteboards using UML diagrams. If you're still able to do this, capture images of the board before leaving to preserve the insights generated during discussions.
For remote teams, conveying ideas can be trickier, often leading to misinterpretations. The best approach is to utilize drawing or UML tools while screen sharing. This method allows everyone to visualize the conversation, reducing misunderstandings and enhancing communication.
Onboarding New Team Members
Welcoming a new hire can be daunting, as it requires a detailed explanation of your system and its architecture. If this process needs to be repeated for every new employee, it can consume a lot of time and resources.
Well-structured documentation can provide newcomers with the autonomy they need to get up to speed. Consider creating an induction plan that includes diagrams, visual representations, and even videos to streamline the onboarding process.
Designing Isn't Just for Architects
In large corporations, system design typically falls under the purview of software architects. Consequently, developers might be tempted to rely solely on their documentation. However, this high-level overview often lacks the specific details necessary for effective implementation.
Enhancing existing documentation with micro-level insights can be crucial in making informed decisions, preventing potential pitfalls that may only become apparent later.
The Limitations of Design Tools
Now, let’s discuss the design tools available for system architecture.
Many of them emphasize aesthetics over functionality. This focus means that users often spend more time ensuring a diagram looks appealing rather than creating one that is easy to modify and maintain. For instance, using Draw.io requires significant effort to arrange elements and maintain visual appeal, which can become burdensome, especially with frequent updates.
Most of these tools aren’t tailored for developers. They may serve managers and designers well, but they overlook the need for efficiency that developers crave.
PlantUML
My introduction to PlantUML occurred during college, where it was the preferred tool for designing diagrams. Initially, I found it challenging due to unfamiliarity with its syntax. However, I now appreciate its capabilities.
What sets PlantUML apart is its code-based approach. Instead of drawing, you write code that generates diagrams. This method accelerates the design process, allowing for easy version control and adaptation of existing diagrams.
In the above image, you can see a sequence diagram I created for my master's thesis. The focus is on defining interactions rather than on visual aesthetics, leaving the rendering to PlantUML.
I store this code in a Git repository, enabling me to track changes, accept updates, and manage it like any other codebase.
The Future of Documentation Tools in Software Engineering
To encourage developers to create documentation, we need more tools like PlantUML. Developers prefer coding over manipulating graphical elements, and time wasted on designing diagrams is unproductive.
However, PlantUML could improve its functionality. For instance, it currently lacks the ability to reference code across multiple pages without duplication, which can be tedious. Additionally, the generated images could benefit from a modernized aesthetic.
Addressing these points would transform documentation into a more enjoyable and efficient task, merging the coding process with diagram creation.
Cultivating the Right Mindset
Ultimately, recognizing the importance of proper documentation is deeply tied to mindset. Breaking old habits can be challenging, but starting with small, useful documentation can encourage others to follow suit.
Create a culture that values design and documentation as integral components of software development. Be a proponent of this mindset among your colleagues.
Thank you for taking the time to read this article. If you have any questions or topics you'd like to discuss further, feel free to reach out. I'm eager to engage!