The Urban Legend of the Human Documentation in Software Development
There are a good number of ways you can make a more junior colleague feel inadequate.
One of the best (if you are so inclined) is to shout them down with some nonsense. Tried and tested.
If you’ve seen the meme above ☝️ you can see the two points I’m going to make:
“Human documentation” is problematic, especially when the knowledge is held only by a jerk
Senior developers can be jerks
Human Documentation
This term (as first written in this blog post) means instead of formal documentation knowledge is simply stored in a person in the team.
So, although teams often neglect formal documentation, they typically do document but in a much less formal way.
Why Documentation Gets Neglected
Time Constraints
Writing documentation takes time — a lot of time. When deadlines are tight, documenting every function, class, or module can feel like a luxury we can’t afford. Developers end up prioritizing shipping features over documenting them.
The Self-Documenting Assumption
There’s a pervasive belief among some developers that their code is so clear and well-structured, that it doesn’t need additional documentation. This is a noble goal, but even the best code can benefit from contextual explanations and examples in practice.
Knowledge Silos
When one person or a small group becomes the go-to source for specific parts of the code, they inadvertently become the documentation. This is a dangerous practice, making projects vulnerable to bottlenecks and knowledge loss if those key individuals leave or are unavailable.
The Dangers of Human Documentation
Relying on team members as living documentation is a risky strategy:
Scalability: As projects grow, so does the complexity. Each developer can only hold some of the intricacies in their head, and relying on them to be a walking encyclopedia is unsustainable.
Bus Factor
The “bus factor” refers to how many team members can be hit by a bus before the project is in serious trouble. High reliance on individual knowledge lowers the bus factor dangerously.
Inefficiency
Constantly interrupting the team lead or other knowledgeable devs for explanations could be more efficient. It distracts them from their work and slows down the whole team.
Breaking the Cycle
So, how do we move away from this unhealthy reliance on human documentation?
Invest in Documentation Tools
Tools like JSDoc, Sphinx, or Doxygen can automate parts of the documentation process, making it easier to keep docs up-to-date with the codebase.
Encourage a Documentation Culture
Promote a culture where documentation is seen as essential as writing the code. Recognize and reward good documentation practices.
Make Documentation Part of the Definition of Done
Ensure that writing or updating documentation is required in your definition of done for all tasks. This can help integrate documentation into the regular workflow rather than something done in a rush.
Conduct Knowledge Transfer Sessions
Regularly scheduled sessions where team members share knowledge about different parts of the codebase can help distribute understanding more evenly across the team.
Use Code Reviews to Enforce Documentation
During code reviews, insist on good documentation practices. This can help ensure that the new code is properly documented from the start.
Senior Developer behavior
We’ve all encountered them — the senior developers who wield their power like a medieval warlord. If you’re unlucky, you work with them. If you’re really unlucky, they are your team lead. Senior developers hold a lot of influence in tech teams, and while many use their powers for good, some seem to relish making life difficult for their junior counterparts.
The Bad Habits of Senior Developers
Gatekeeping Knowledge
Some senior developers act like the keepers of the sacred flame, hoarding knowledge like Smaug hoards gold. They believe that by not sharing information, they maintain their position of power. This is detrimental to team cohesion and growth.
Imposing Arbitrary Standards
They insist on their way of doing things, even when it’s not the best or most efficient method. Their code reviews are less about improving code quality and more about enforcing their personal preferences.
Disrespecting Junior Developers
This can range from not taking their suggestions seriously to outright belittling them in meetings. It’s a quick way to demoralize a team and discourage new ideas.
Micromanaging
Instead of trusting their team, these senior devs feel the need to oversee every minute detail. This stifles creativity and prevents junior developers from growing into their roles.
How to Be a Better Senior Developer
Share Knowledge Freely
Make it a habit to document your processes and share your knowledge. Encourage questions and foster an environment where learning is continuous and accessible to everyone.
Embrace Different Perspectives
Just because you’ve always done something a certain way doesn’t mean it’s the best way. Be open to new methods and ideas, especially from your junior team members.
Mentor, Don’t Manage
Focus on mentoring rather than micromanaging. Guide your junior developers, help them grow, and give them the autonomy to solve problems their way.
Respect and Recognize
Respect the input and effort of all team members, regardless of their seniority. Recognize good work and provide constructive feedback to help everyone improve.
Conclusion
The next time you find yourself channeling Walter White, remember that great documentation is a team effort and should not all be placed on a senior developer.
A team should develop a cultivated habit rather than a choice that is passed from coder to coder until someone isn’t busy enough to claim they haven’t sufficient time.