What’s the hardest part of software development?
Some say it’s cache invalidation, some say it is naming things. We say it’s mostly not about code, but about people.
Or more specifically, about how people communicate concepts, complex thoughts, architectures, and decisions. In one phrase, the most difficult part of software development is documentation.
As Uncle Bob would say, how software developers write documentation and communicate makes the difference between ‘MacGyver’ developers and pro developers.
It’s not the number of years in the industry, not how many lines they can write in a day, not if they know what’s a monad or a generalized algebraic datatype, or how fast they can find the solution to a complex problem.
Documentation is critical for smooth business development.
Not when you write the first MVP of the product with your one outsourced developer, but really soon after, when you build a team.
When teams come together, the importance of strong documentation becomes obvious. Without it, onboards will fluster and curse the world, veterans will lose time trying to find the knowledge the team requires, and thus the team is slower.
And unhappy! And of course, in our hyper-competitive business world today, having an inefficient and and drowsy team is a recipe for failure.
Why most developers don't write documentation
Generally speaking, it starts with the first team members, and the process and culture propagates as the team grows.
Most developers like to write documentation and have good intentions, but when the team gets used to doing things a certain way, it's very hard to turn around.
When the team becomes aware of the problem, makes a plan to turn around their habits and sticks to it, things start rolling, features get shipped, bugs get squashed, refactors become a piece of cake, smiles start to appear, compliments get tossed around and inevitably, your customers will feel it through the better product they receive.
What type of documentation they write, when they do
Most teams create some basic type of documentation, in the form of code comments.
More advanced teams generate some HTML from their code comments and host it somewhere internally, so more people from the organization can reach it.
The problem with both types of teams is that they wrongly believe this is enough or even believe this is good documentation. Unfortunately, for most situations, this is far from the truth, because this type of documentation describes ‘what’, not ‘why’ and ‘how’.
Performant teams communicate on another level. First, they are aware that their team is not only made of people who read code.
We have QA Engineers, Product and Project Managers, Architects, Solution Architects, VP of Engineering, and even CTOs would maybe want to know some of that precious knowledge.
Should they just learn git and git pull to the latest branch that only software engineers know what’s in?
What type of information is considered documentation?
Most of us would agree that documentation is: diagrams, data flows, changelogs, API methods, REST APIs.
In addition, there are some valuable types of documentation that are not widespread believed to be ‘documentation’ per se, like: technology decisions, whiteboard sketches, complex thought-trains that can get explained only by text, performance bottlenecks, architecture flaws (and/or tradeoffs), latency maps, and more popping up every day as software solves bigger problems and gets more complex.
How can Archbee help?
Archbee provides an easy to adopt solution for technical documentation that is specifically tailored to software development teams. We've studied many teams and their workflows, we've identified common use cases and coded them into our software's DNA. When your team picks Archbee, you are guaranteed to see upsides like team happiness, synergy and productivity within less than 3 months of using our product.
Try Archbee's full range of features with our free 14-day trial.
