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.

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.

Archives

Blogroll

Connect

About the photo

This is a brown pelican that I watched while visiting the beach at Hilton Head Island, S.C. in Summer 2016. Pelicans fascinate me and I can't help but think that they enjoy gliding over the waves at least as much as i enjoy watching them.

For the photo geeks, I took this photo on June 19, 2016 using a Nikon 200-500 f5.6 zoom lens at 420mm at 1/1250 sec on my Nikon D7000 camera. The image was cooled down in Lightroom to give it a bluer-than-natural look for this web site.