Do design philosophies belong in Quick Start guides?
In "Documenting the Undocumentable", James Hague argues that the most important part of a software tool to document is the design philosophy behind it. For example:
Why is it so much work to change the fonts in a paper written in Word? Because you shouldn't be setting fonts directly; you should be using paragraph styles to signify your intent and then make visual adjustments later.
These assumptions about the way you should use the tool are sometimes left undocumented, or at least somewhat buried. Hague would like to see them in the Quick Start guide, which is:
… the tip of the documentation iceberg … the only thing a user will read before clicking around and learning through discovery or Google.
No argument from me that these kinds of assumptions deserve careful attention in the documentation. I've read enough user guides for graphics tools, IDEs, XML editors, and the like, that consist of short, mechanical, button-pushing procedures without any of the information that would help me understand the best way to achieve my goals with the tool. (This, of course, is not minimalism but simply poor documentation.)
The question is: where should this kind of information go? To continue with Hague's example of paragraph styles, I first learned about these while writing a book using Open Office Writer. In that tool's manual (see the current PDF version), I must have come across this note in the procedure on formatting paragraphs:
It is highly recommended that you use paragraph styles rather than manually formatting paragraphs, especially for long or standardized documents. For information on the advantages of styles and how to use them, see Chapters 6 and 7.
And indeed, wanting to do things properly, I did go off and read Chapters 6 and 7, which converted me to using paragraph styles (and indirectly started me on the path to structured content).
Would I have read this if it was in the Quick Start guide? Probably not, as I just downloaded the software and so didn't have the printed version. Do people generally read printed Quick Start guides when they have them? Not always, in my experience. I agree with Hague that this valuable information needs to go somewhere really obvious and accessible, but I think that place is with the main docs, in an online format. (There's no harm in at least mentioning it in the QSG too, though it seems hard to do these kinds of fundamental working patterns full justice in that limited space.)
And where does this kind of info belong within the main docs? As the top half of a long page with the kind of goals that people search for somewhere further down the page? Linked prominently from any related page targeted at achieving a specific goal? Linked as in the Open Office docs, with a note accompanying the link highlighting that this is how things work, or how they work best? In a very general sense, I prefer the last option, but actually I don't think there's any one correct answer. As always, the best content is achieved through the painstaking but rewarding process of listening to what your customers need (that's listening on all available channels: quantitative and qualitative), seeing how they use your content, improving the content, and listening again.