I'm often asked to explain what value I think documentation provides, what role does it play in making a good product. Most people think of documentation as a neccessary evil or just a bunch of words that are better left unread. Many people's experience with technical documentation, mine included, is frustrating. It never seems to guide on the path to doing the thing you really want to do. It may tell you how to use the "burn and dodge" tool or "use the process designer," but it doesn't really tell me how to selectively darken a portion of a photograph or assemble my services into a process flow.
So what does most documentation do? It explains the features that make up a product. It tells the user how to use the process designer and all of the paths to getting there. It may even mention a few of the reasons a user may want to use the process designer. The problem is that most users don't want to use the process designer. They want to assemble their services into a process flow. More likely the user has an even more specific goal such as assembling my services into a sequntial process flow so that they look like a single service to my customers.
So what should documentation do? It should provide a user the information they need to darken a portion of a photograph. To accomplish their goal, the user will need to use the dodge and burn tool. However, they need to use it in a specific way (only one way) and they are more likely to find the informaiton because it relates to their goals.
Why does documentation often look like feature documentation and not user documentation? One: product release plans are often a list of features and not a list of users stories. Two: writers don't have access to customers to actually understand their goals and needs. Three: the myth that writing user focused documentation is too expensive. Writers can get out of the trap by pushing on product owners to provide user stories and access to customers. Writers can also start pushing back against the myth. It takes a lot of time to fully document the seventeen ways to implement a widget and all the stuff around it. It takes a lot less time to figure out why the user wants to implement that widget and document the best path to accomplishing the goal. It is also a lot more valuable.