When working on a development team, transparency and knowledge sharing are essential in order to keep track of changes in the code and limit vulnerabilities. This is why creating proper documentation should be considered a top priority for all developers.
It is also why the consequences of missing or inadequate documentation can impede application updates or new feature additions that can adversely affect both the end user (by delivering a buggy product that the missed delivery deadline) and the organization itself.
However, even knowing this, the tech industry is still facing the ongoing issue of poor documentation practices.
Steve Brothers, president of the artificial intelligence software company, Phase Change Software, attributes this to a lack of interest on the developer’s part. “They don’t feel like they’re paid to do it, so they don’t see the value of it in large part,” he said. “Some do, but most just don’t seem to.”
Frédéric Harper, director of developer relations at the API-based product organization, Mindee, also touched on this point, saying, “The thing is… developer documentation is often an afterthought… Many [developers who don’t document] do not think a lot about the end users, they don’t explain enough, there’s a lack of consistency… and that doesn’t make for a super good experience for end users.”
On top of that, Brothers explained that even when developers do put comments in a line of code, they are oftentimes inaccurate. This can result in an unintended downstream effect that will negatively impact the next developer’s ability to contribute to the project.
According to Brothers, failing to propagate changes to the documentation limits the amount of information that the rest of the developers working on the project have access to and, therefore, can result in slower and sloppier development.
This leads to the question: knowing that there are so many negative side effects, why are developers still not taking an interest in documentation?
Brothers inferred that time constraints may be to blame. “The pressure is not on putting comments in code, so maintenance is not a thing… It is more important to get the job that’s in front of you done in a timely manner. Frequently, organizations do not want to pay that time price,” he said.
He also spoke about how there are some developers that assume nobody else will be working on their code and so explanatory documentation feels unnecessary.
“From that standpoint, there is no motivation to do it if I’m the one who is going to be maintaining it. Obviously, to the organization there is a benefit if somebody else is going to be maintaining the code, because regardless of how complex it is, those comments would be beneficial to somebody who has never seen the code before,” Brothers explained.
On the other hand, there are those who don’t partake in proper documentation because they think that their code is so elegant and clean that even if another developer had to read it, it would be easily understandable.
Harper also spoke about this, saying, “It could also be a little bit of pretentiousness, like ‘I’m good so everybody should understand it,’”
Having either of these mindsets can lead to inaccurate, incomplete, or missing documentation which can cause the whole organization to suffer.
“You end up with fixes being wrong, and that consequence results from the documentation not directing the developer to go to the right place to fix something. Those are standard market failures,” Brothers said.
He went on to explain that the repercussions of these failures can range from bringing a system down, to missing the regulatory requirements in the code, to a severe loss of time, and therefore, suffering productivity.
“There is no question that the amount of time it takes to identify the code you’re looking for, which is what you have to do if you’re going to fix a bug, that is 80% of a developer’s time right there… and all that does is get exacerbated if there are no comments or the comments are wrong,” Brothers explained.
Additionally, Harper said that incorrect or missing documentation can harm a company’s reputation in the industry. This is particularly true when other developers are the target audience for the end product.
Harper explained that developers are usually more sensitive to the experience they have when using a product for the first time, and so the impacts of poor documentation practices will be felt particularly hard.
“Developers are really quick to move to another product, so that creates a missing opportunity for the company to gain and retain more users,” he said.
Brothers also pointed out that having proper documentation helps tremendously down the line because the requirements for code are unpredictable and can change at any time depending on the wants of the product owner.
When it comes to fixing these issues and ensuring that documentation is top of mind, Brothers said that making it a part of code reviews is a possible answer.
He explained that currently it is not customary for comments in code to be required in order to satisfy a code review, which also feeds into the disinterest developers are exhibiting.
“If you’re an Agile development shop, you certainly could make comments a part of the acceptance criteria for the completion of a story, so that when the work is completed it has to have comments in it,” he said.
‘Productize’ documentation
In an SD Times-led conversation on the Dev Interrupted Discord server, Chris Downard, VP of engineering at GigSmart, weighed in on why he feels documentation often slips through the cracks of the development process.
Downard explained that the majority of developers write average to weak documentation because it is not part of the actual feature delivery scope, and so, they do not see the value that it has.
“In a perfect world documentation should be part of the deliverable and it should be ‘productized’ meaning it’s treated like a product,” he explained. “Users (your other devs and product delivery members) can actually use it to answer questions before they go to ask others. But until your docs are good enough and discoverable enough to do that, it won’t happen.”
Downard also touched on the possibility of offloading documentation to those rare developers who have a knack for it.
However, while doing this ensures that code has the proper comments, it also works to breed underskilled writers and that could also have detrimental impacts to the organization.
Downard then stressed the importance of making documentation an organization-wide priority. He suggested supplying developers with a “needs improvement” example as well as a “top notch” example so that developers can measure their own documentation against the two.
“But it’s also not enough to simply throw it over the wall and be like ‘we need to write better docs so definitely start doing that.’ And if it’s something you really want to improve on, you have to measure it. Because if you’re measuring the number of MRs that get merged or story points or whatever, and writing documentation isn’t included on any of those things, no one will ever write it,” he said.
New tools for generating documentation automatically
Brothers also explained that there are tools coming onto the market now that would work to automatically generate documentation so that all the developer would have to do is make sure that it’s correct.
These tools would ensure that documentation is present while also accommodating the time pressure that developers feel to deliver projects on time.
Brothers also discussed PhaseChange’s AI documentation tool, COBOL Colleague, which is intended to tackle this issue by mimicking the cognitive efforts of developers.
“What our tool does is automate the developer’s thinking process,” he said. “We’ve taken a collaborative AI approach for this tool to work with the developer so that when they describe the behavior… what our tool does is return only the code that is relevant.”
According to Brothers, this tool works to eliminate the need for documentation altogether because the user is not actually reading any code.
With COBOL Colleague, the developer would no longer have to search through several different lines of code, but rather they would only be presented with the code that matters as well as any other helpful data.
This tool and others like it also help businesses maintain the necessary knowledge about the code even if the developer that originally wrote it leaves the organization.
According to Brothers, when documentation is done the right way, information does not leave with the developer.
Outside of investing in tools though, Harper said that investing in people could work to solve these issues.
He said, “I really think that you should hire a technical writer or at least a developer advocate that is going to take on maintaining documentation as a big part of their job… Because in the end, the product and the documentation go together and one cannot live without the other.”
