Yet another study is out, this one from UC Berkeley: Most developers think we should spend more time on documentation, showing that developers, when asked, say that they want more documentation, or, in this case, need to spend more time working on (writing?) the documentation for the software they use and write. The list of related studies is long (by software-documentation-related-studies standards, anyway), a few of which I mention in A brief history of API Docs and in my bibliography.
I understand the the desire to ask developers (over and over, now) questions like “do you have enough documentation?” “what’s wrong with the documentation?” “What do you want to see more of in documentation?” and so on, when those are the questions on your mind. However, that type of question has been asked for over 15 years and the answers haven’t changed.
At this point, we should just assume that,
Developers will always tell you that they want more documentation.
They always have and they always will.
If you want to know why they express this need for more documentation, my hypothesis (based on previous research) is that it’s…
Because developers can’t find the documentation they need when they need it.
I’ve expressed a value-related view of this, in that developers write as much as they think is worthwhile in our paper, API documentation and software community values: a survey of open-source API documentation; however, I think a simpler reason might be that it’s not a question of quantity.
A better question (i.e. the next question) to ask might be, why can’t developers find the documentation they need? The answer isn’t as simple as, “we don’t have enough of it.”
Here are two logical alternatives (as identified in previous research listed in my bibliography):
- The documentation is not there to be found–a case where more documentation would help (assuming it’s the right documentation, of course).
- The documentation exists, but can’t be found for some reason (such as, navigation challenges, terminology mismatch, too much irrelevant content, and so on)–a case where more documentation will only make the problem worse.
Because solving the wrong problem only makes the situation worse, it’s vital to understand the problem before offering up, let alone implementing, a solution.
Fortunately, both situations can be evaluated by using the same tool–understanding the context of the documentation. The good news is that can be done by asking the right questions, as I talk about in my presentation on Audience-Market-Product.
The problem of developers not finding the documentation they need, will only be solved by understanding what they need and when they need it, and then, how they look for it. This problem won’t be solved by automatic documentation generators (that solves quantity not quality). It might be solved by some AI (because AI is magic). I’d like to say that it could be solved by better instrumentation of the content to know how the documentation is being used (but that only works once you’ve published enough of the right documentation to study).
Really, it all comes back to knowing your customer/reader/developer. There’s just no way around it. More to the point, it comes down to knowing your customer’s journey and where they need documentation along that journey.
Documentation should greet your customer (developer) where they are in their journey and help them along their way.
Returning to the thesis of the recent study. I’ll agree that developers need to spend more time on documentation, but not necessarily writing more documentation. Where developers (and technical writers) need help and should spend more time with regards to documentation, is not in the generation of the documentation, but in finding better ways to understand their customers such that they can apply that understanding to write more effective documentation.