Developer Documentation

Developers don't like writing docs, what's the alternative?

Oct 20, 2020

I don’t often land on Reddit, mostly because doing so sends you down the Internet wormhole. All of a sudden, you realize you lost half the day shouting at people being wrong on the Internet. My one indulgence is r/ProgrammingHumor and I saw this earlier in the week.

No matter how much you try, it can be hard to guide users down the right path. I plead guilty here as I often skip over all the introduction videos, guided tours, and setup wizards. Once I managed to delete my entire website just because I was too anxious to try out a new tool. The combination of over-eagerness and hubris can be a destructive mix.

Luckily, developers are generally prudent and actually use documentation. In the 2018 Stack Overflow survey, 83% of developers said they use the official documentation. That is even higher than the percentage that rely upon Stack Overflow!

If developers definitely use and value documentation, what it is deal with them not wanting to document their code? I asked a few forums both inside AWS and some external developer advocate communities who is writing the documentation?

Turns out, it is everyone except the people that write the code behind the feature or API. Many places employ tech writers, other places it is the product managers, and in some companies, the developer advocates and implementation teams are writing documentation. Everyone it seems other than developers.

To be fair, much of the documentation needed is for end user audiences. The first product I ever worked on, an internally built customer relationship management (CRM) system, was for an audience that was definitely not technical. I was not only the developer, but also the tester, sys admin, database admin, deployment manager, and product manager. I also ended up being the tech writer. Having decent writing skills though meant the documentation part was manageable.

Documentation is still not easy. I had to organize the outline the steps of the user journey to get setup and started on the system. I had to test the onboarding and all the user flows, then run through each key feature and scenario using dummy data I had input. Each key step needed a screenshot. Sometimes there were weird bugs, edge cases, and out of bounds situations that needed to be explained. Then and only then could I actually get to writing, which itself required what I called the Three “Ity’s”:

Clarity – Are the words and phrases used easily understood?
Brevity – Is the text concisely written, eliminating excess words?
Simplicity – Does the text convey the idea in the most effective way possible?

Even with a quality assurance step (me bribing one of the sales reps to go through docs), the documentation never captured all the things users do. Some would forget to save changes, some would put information in the wrong fields. Then I had one user manage to accidently delete the entire app from their laptop, on multiple occasions.

Because of the importance of end-user documentation, there will always be someone to do the work. Probably the most important function of any developer advocate is to create content that is either documentation or things that supplement documentation such as demos, tutorials, code snippets, API examples, and workshops. And when the documentation is wrong or outdated, they dive in to update the material.

So who are the developer advocates for the engineers inside the organization trying to make sense out of code they do not understand?

The problem with developers writing documention is three-fold. First, writing documentation is a skill, one that developers rarely ever bother to acquire or hone. Second, in the queue of priorities, documentation always ranks towards the bottom of the list. The most important reason though is the fact that developers are not incentivized for writing good documentation. Even if they are tasked with creating documentation, it is not a task that is deemed important. After all, engineers are paid to ship, not document.

We know that someone is writing documentation, however intermittently. Documentation often becomes the “glue work”, the invisible work that is needed but goes unrecognized. It is often someone on the team that finally can’t stand the inefficiencies and takes ownership to write the documentation themselves.

When documentation is created, we know it’s valuable. How do we know? When developers using the documentation complain loudly about how bad or outdated it is. Then the cycle begins again on finding another glue worker to get mad and fix the documentation, without any glory, recognition, or points towards a future promotion.

What is the answer then to filling the developer documentation gap? You could gaslight them as the beginning of this presentation on documentation avoidance suggests:

However you probably care about software delivery performance and enabling developers to be productive. Here are four options to providing developers the much needed documentation they need.

Write self-documenting code – This is good in theory, until other teams need to use the code either directly or through an API. The bigger challenge though is this advice often falls into a similar category as coding standards. Everyone is in agreement, yet no one adheres to what is agreed upon. There is also widely varying degrees of skill and differences in code quality and readability between senior and junior developers.
Just-in-time documenting – Rather than doing coding work and documentation separately, record useful information about the code while code is being written. This is most often done in comments, commit messages, readme files, and wikis. The problem is trying to search for information and getting anything meaningful from it. Remember most developers write documentation from their perspective, not the perspective of others to understand.
Community-guided documenting – This is a more collaborative means for distributing the work of documentation. Forums, wikis, Q&A, and messaging apps are the most common tools used to foster greater collaboration and participation. In some instances this works well if the culture is oriented towards sharing. Most large enterprises and in certain cultures experience real problems with adoption and fear of being wrong publicly. The other barrier is the cold start problem that slows the roll out of these platforms due to the lack of content and users.
AI-driven documenting – The previous three options still rely upon developers, which is the weak link in writing useful documentation. Developers hate writing documentation and are not very good at it, so what if we tool developers out of the equation? AI has made significant advances over the past few years in understanding semantic context of languages. The same algorithms can also be tweaked to apply AI to reading and understanding code. This is the approach that Singaporean based startup, Quod AI, is taking, applying their technology to cloud hosted and on-prem codebases to make code faster to find, easier to understand its context, and better at identifying dependencies in the code. The advantage of AI is that it can search code and the artifacts of code across multiple repositories and tools. The biggest benefit though is that AI is not impacted by culture and it avoids the cold start problem since AI is generating the documentation as soon as it is connected to a repository.

We are already comfortable with AI handling many common everyday tasks. AI drives most language translation, recommendation engines, and mobile assistants. It even handles some driving tasks and airline autopilot systems. The next step for AI is to automate away many of the tedious tasks that impede developers from being productive. The next logical step is to replace human documentation with AI generated documentation assisted by developers when needed.

How is documentation created today in your organization and who write the bulk of it? What are ways that you have tried to spur developers on to contribute to documentation?

DEVBIZOPS

Discussion about this post