Traditional wisdom in the world of technical documentation has it that you think of three main categories of information for a product:
- Training: hand-held, guided, on-rails and training-wheels exploration
- User: task/topic-based instructions
- Reference: concepts and components organized for lookup
For example, if you want to speak a new language (Chinese or Italian, say), you can imagine interactive oral and written practice (Training), phrasebooks and discussions (User), and dictionaries and grammars (Reference).
“T” and “R” material is usually in plentiful supply, “U” less so, particularly at an early stage of a project. The development process often produces “R” material as part of the design and specification process, and “T” material is relatively easy to produce by early adopters, and by developers if they have time. It can be problematic if documentation blurs the boundaries of these categories too much, jumping from conceptual overviews to lists of available functions, depending on the author.
Problems arise when, in the heat of battle, in the face of rapidly approaching deadlines, users turn to the documentation, and find either simplistic “T” material which doesn’t describe their problem, or “R” material which doesn’t quickly provide the answers they seek. (“Congratulations on purchasing this fire extinguisher. Please read the following chapters carefully before attempting to put out a real fire…” is not what you want to read when you’re on fire.)
And of course, if someone provides task-based instructions for every single scenario, you could have problems finding the one you want.
Descriptions of common workflows is always a good thing to have, though, not just for package management, but for package development, and debugging. Currently, the Julia manual has plenty of room for them, but I’d hope to see better search tools if the documentation gets very much larger.
