One of the metaphors I use to explain the distinction between documentation and guidance is Driver’s guide vs. Owner’s Manual. While I could go into the finer details, it’s a good starting point. From an owner’s manual, I expect to see how things work and how they’re intended to be used. From a driver’s guide, I expect “how to get the most out of it.”
I see the two bodies of information as very complimentary. I also see them as distinct. I wouldn’t want to mix my driver’s guide with my owner’s manual. However, I do want to be able to seamlessly go from one to the other, when I need to. I also want my owner’s manual written by the people that built it and I want my driver’s guide written by the people who use it in action.
In practice, I use my owner’s manual when I care and tune my RV. When I take a cross country trip, I use my driver’s guide. Knowing this distinction helps me choose the right tool (information set) for the job, as well as set my expectations about the type of information I’ll find.
I think finding the right metaphors is important because it helps illustrate a distinction that’s not always obvious or hard to explain. I don’t think guidance is yet a pervasive part of our technical landscape, and yet I see it as a key differentiator between success and failure. By pervasive, I mean I can use any product or technology and easily find the driver’s guide. I mostly see owner’s manuals.