I have a controversial opinion: When developers say something doesn’t work, most of the time they simply don’t understand how it works or why it was written that way.
Forgive me for sounding cynical. It’s perfectly reasonable to say something doesn’t work how it should but, all factors considered, I don’t think this notion’s as common we’d like to think it is. Instead, I think we come to this conclusion because it’s easier than struggling to comprehend a piece of work written by someone else. The challenge in attempting to get our heads around a piece of complex code or system feels insurmountable and labelling it as broken gives us more time to attempt to solve the problem at hand (or decide if there is one at all.) We also have a tendency to want to put our own stamp on things, which we wouldn’t be able to do if everything was already perfect.
This misunderstanding is usually a disconnect between the person who originally carried out the work and the person who’s currently working on it. At some point in time, information was lost. This might include: a description of the original requirements (the problem), an explanation of why certain decisions were made (context) or merely an explanation of the implementation itself.
A project’s requirements can be relatively easily documented at its start but something most teams forget is to update these documents as the requirements change, as a product of day-to-day decision-making. It’s important that this document or specification is maintained by someone likely to be involved in these decisions going forward and the right people are notified when it changes, which usually can be automated in some way.
Understanding the reasoning behind (why) certain decisions were made is a little different in that it’s everybody’s responsibility to document it. You’ll know it’s failed to do this properly if at some point you hear people say “I don’t understand why it was built this way”, because invariably there’s context missing.
The mistake is confusing this with stupidity. Rarely do we just blindly do things without giving them any thought and so it’s always best to assume that past decisions were made with some level of consideration. Perhaps the tech lead at the time wanted to use a particular technology, or there were knowledge gaps in the team, or the deadline was too tight for the ideal solution. Perhaps the person who made the decision holds a different opinion to you.
Unfortunately, most teams don’t foresee a lack of documentation being an issue until it becomes one, for example when a developer makes a breaking change by deciding to refactor a piece of legacy code. In most instances, refactoring code (with the intention of making it better) is something to be celebrated and yet by trying to do something she thinks is beneficial, but acting on incomplete information, she inadvertently makes things worse. Furthermore, the situation creates a sense of fear around particular parts of the codebase, especially for new team members who introduce new abstractions instead of tackling what’s already there head-on. As you can imagine this only exacerbates the situation and when left unaddressed, creates a precedent that it’s better to skirt around “ambiguous legacy feature X” than to understand and document it.
As I found while researching the problem of documentation in technical teams last Summer, software developers hate writing documentation. The majority of us don’t consider it to be something that should fall under our remit, nor do we think it’s our responsibility to write well. The majority of us don’t even feel our code should need documenting if it’s written in a “clean” way. I’ve always thought it a little ironic that some developers obsess over the clarity and cleanliness of their code but don’t hold written communication in as high a regard.
I suspect that many of us simply don’t feel we owe anything to our successors, those taking over the reigns at some point in the distant future. As developers we need only focus on what’s happening in the present and the problem we’ve been tasked to solve now. Any time spent dwelling on something after the matter is time we can spend solving other problems. This thinking is ignorant and short-sighted and probably more often than our successors do we need documentation to understand something we’ve written ourselves (months or years prior). I once worked with a back-end engineer who one day was searching for the answer to a question on Stack Overflow only to realise he’d written the nominated answer about a year before.
While I appreciate how intimidating the blank page can be, to write something, anything, words on a page, is better than to not write anything at all, as long as the meaning is clear. Managers must do everything to lower the barriers to creating documentation, even if it means removing internal processes, leapfrogging hierarchies etc. There’s no place for overzealous GSuite protectors here; Most modern editors have some concept of revision history so there’s no risk of anything being “messed up”. Furthermore, as important as writing documentation is, ensuring teams have access to and the ability to search for relevant documentation is equally important.
Writing documentation is just one product of a culture that encourages knowledge sharing. A senior developer who spends his time mentoring less experienced team members should have no objection to sharing his reasoning in written form (and probably enjoys it more than you’d think, because who doesn’t like talking about their own ideas?) A team that is continually finding opportunities to create and share knowledge is a team that continues to grow.