Software Engineering, Project Management, and Effectiveness
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.
It is not about what it does but how to use it (read this to understand the difference Driver's Guide
“As to methods there may be a million and then some, but principles are few. The man who grasps principles
Book building is art and science. I've built a few books over the years at patterns & practices.