Few tasks can make a developer groan more than the process of documenting their code. As important as documentation is, it’s a task that has always gotten set as a low priority for developers, which leads to problems down the line.
Postman’s 2019 State of API survey found that over half of respondents felt that API documentation was “below average or not well documented.” In addition, Coding Sans’ 2020 developer survey showed that sharing knowledge was the biggest challenge in software development.
When talking about documentation, it’s important to make the distinction between two main types. Internal documentation is used to share knowledge about a particular piece of code with fellow developers, or developers who might be working on that piece of code in the future when the person who wrote that code might no longer be around. External documentation is documentation for consumers of a product. This includes things like release notes or product manuals. “If your customers can’t adopt your product and use it well, often you will lose that customer, or they will become frustrated and may look at other products,” said Kendra Little, DevOps advocate for Redgate.
RELATED CONTENT: How knowledge management systems support software development
One interesting evolution of customer-facing documentation over the last few years might be changing its place in the software development life cycle. Some companies have taken to integrating documentation into the product itself. For example, rather than a user having to search for a specific page in web documentation when they want to learn more about a feature, the application itself will include a pop-up that appears when an object is hovered over that provides more information. “Instead of asking a customer to go look at our external page of releases, it’s in the tooling to have a place that notifies your customer ‘hey we have this new feature and here’s where you can go read more about it,’” said Little.
Joseph Spurrier, head of engineering at cloud governance company cloudtamer.io, encourages his team not to think of features as simply buttons or forms, but as the know-how that goes along with that feature. “We develop a variety of documentation to share that know-how: basic pop-up labels to help identify unique icons, tool tips that provide a sentence or two to help the user complete the task, and context-sensitive help accessible from within our application and hosted on our support portal,” he said.
Little believes that it’s no longer enough to just have a set of web pages that users can find by searching. “Yes, you do need to have that, but you also need to help them find it at the relevant time,” said Little.
According to Asif Rehmani, CEO of VisualSP, a company that provides in-context training solutions, no matter how skilled a person is, eventually they will come to a part of an application they’re not familiar with and will have questions. At that time, it’s not efficient for a user to have to go search for answers. It’s much better for those answers to be surfaced in the moment, which prevents the flow of work from being disrupted. A short snippet of documentation that appears in a help icon that you can click on is much more effective than long documentation that isn’t as accessible when you need it, Rehmani said.
Making documentation context-aware can help users better get the information they need, and the same principles can be applied to end user training as well. Context-aware training educates users based on what they need to know at any given time, rather than dumping all training on them upfront, before they even get to access or explore the systems they’re being trained on.
Rehmani said that traditional training has its place in certain situations, such as for administrators or power users, but that most end users don’t need all that training up front, especially for tools they won’t be using for another six months to a year.
Rehmani thinks of this context-aware training less as training, and more as helping. “Think of it like this. How many times have you had someone come up to you and say ‘can you train me on this?’ That’s just not what people say. When people come to others they’re using the word ‘help.’ They’re saying ‘can you help me with this?’ It is truly help that they’re looking for to accomplish the task at hand at their moment-of-need. Context sensitive training does exactly that. It provides help at the moment of need.”
Rehmani believes this microlearning method of knowledge transfer will become the norm. Just as applications like Twitter, Snapchat, Facebook, and Instagram let users consume small bits of information, that methodology will need to be adopted by organizations as well.
Historically, and even still today in companies that haven’t adopted these context-based methodologies, documentation has always gotten shoved further and further down the priority list. This is especially true in environments where higher-ups are demanding a lot from developers, leaving them little time to document their work.
“Maybe traditionally developers have been a little bit sparse on documenting things and it’s been an extra chore that they have to do after work on implementation has been done,” said Heikki Nousiainen, CTO and co-founder of managed database provider Aiven.
Shayne Sherman, CEO of IT company TechLoris, agreed, adding that while developers might begin a project with the intention of adding in good documentation, things quickly fall apart as deadlines near. For example, he has seen a number of developers over the years start off where “each method has a great comment block, new services and functions are added to the documentation repos, the sun is shining and the birds are singing. But, as the iteration ends, QA gets their hands on the code, and the deadline looms near, clouds gather and the birds are silenced. Suddenly all we care about is getting the code out. Methods change and the documentation isn’t updated. New methods are written and are never documented at all.”
Sherman believes there are a few ways that developers can get control back over this process. He recommends developers pad their tasks with the understanding that documentation is a requirement. He also advocates for including documentation in the definition of done. Another way that developers can stay on top of things is to include it as part of peer review, he explained.
Code collaboration platform CodeStream is tackling this issue of knowledge sharing with their flagship product. “We believe that collaboration solutions that are specifically designed for developers should become the foundation of useful documentation,” said Claudio Pinkus, COO and co-founder of CodeStream.
They believe in “on-demand” documentation, which Pinkus believes is more efficient than if a developer were to try to document every single thing about the code that someone might have a question about somewhere down the line. “When a developer implements a new component or module, and wants to attach documentation, instead of trying to figure out in advance what others may not understand, CodeStream allows the consumers of that code to more easily ask questions, and “pull” the information from the authors,” said Pinkus. “We have implemented an in-editor interactive FAQ approach that captures the question-and-answer interaction and attaches it to the code it refers to. So not only do the missing pieces get filled in to solve the immediate need, the discussion is saved alongside the code for the benefit of the next developer who consumes the component or module.”
According to Nousiainen, ultimately the key to moving documentation higher up on developers’ priority lists is to get them to understand the value it will bring to them, whether that be through easier maintenance and refactoring down the road through good internal documentation or reduced support tickets through better customer-facing product documentation.
Noisiainen believes that another key factor in getting documentation done properly is having upper-level management push for it. “Management often needs to make a push to start the initiative and then ensure there’s enough time allocation and prioritization to keep the practice ongoing.”
In fast-paced development cycles, it can be harder to keep up with documentation, but it’s not impossible. For example, at Aiven, where they do two production deployments a day, they have discovered and practice a documentation system that works for them. They consider design documentation as part of the source code, meaning that documents are reviewed as part of the change management process, said Nousiainen. “It’s quite a fast-moving target,” he said. “It’s even more important that the documentation really follows the same life cycle. And it’s natural for us to keep that in the same delivery, or manage it in the same fashion as the implementation itself.”
Automation plays a key part in this, too. Little explained that documentation has the potential to actually save developers time if they work it into their automation. “I think what actually is the truth about documentation and the reason that a lot of people can dread it, is that it involves a lot of creation of a document, putting that in an email, and sharing it with people, and a lot of these manual steps that are quite time-consuming,” she said. “If you can build that more into an automated pipeline and start chipping away and removing those steps and finding the tooling that lets you do little bits of this as part of your workflow, it makes it not only less time-consuming but it makes it a lot more pleasant to do.”
