Diataxis/Reference

• Reference - Diátaxis

  • What is Reference Documentation?

    • Reference guides are technical descriptions of the product and how to use it effectively
    • Reference material is information-oriented and serves as a reliable source of truth
    • Contains propositional or theoretical knowledge that users consult during their practical work
    • The purpose is to describe, as succinctly and clearly as possible, in an orderly and systematic way
    • Unlike tutorials and how-to guides (which are led by user needs), reference material is led by the structure and nature of the product it describes
    • Reference documentation provides users with certainty and confidence—firm platforms on which to stand while they work

  • Key Principles of Reference Documentation

    • Describe and Only Describe

      • Neutral description is the key imperative of technical reference
      • Maintain austere and uncompromising style focused on factual information
      • Focus on neutrality, objectivity, and factuality without opinion or speculation
      • Avoid introducing instruction or explanation (link to how-to guides and explanations instead)
      • Aim for accuracy, precision, completeness, and clarity in all descriptions

    • Adopt Standard Patterns

      • Reference material is most useful when it follows consistent, recognizable patterns
      • Place information where users expect to find it, in familiar formats
      • Use standardized presentation that allows users to quickly locate what they need
      • Consistency helps users navigate efficiently and builds trust in the documentation

    • Respect the Structure of the Product

      • Structure documentation to mirror the logical organization of the product
      • The conceptual arrangement of the system should be reflected in the documentation
      • This parallel structure helps users work through both the documentation and product simultaneously
      • Like a map corresponds to territory, reference should correspond to what it describes

    • Provide Examples

      • Examples illustrate usage without falling into explanation or instruction
      • They provide context while maintaining focus on clear description
      • Well-chosen examples can succinctly demonstrate functionality and proper usage

  • Characteristics of Good Reference Documentation

    • Austere: One consults reference material rather than reads it from beginning to end
    • Authoritative: No doubt or ambiguity; wholly reliable and definitive
    • Map-like: Tells you what you need to know without having to explore for yourself
    • Structured: Organized according to the logical structure of what it describes

  • Common Pitfalls to Avoid

    • Mixing reference with tutorials or how-to content, creating confusion about purpose
    • Assuming auto-generated reference is sufficient documentation on its own
    • Including opinions, speculation, interpretation or marketing language
    • Using inconsistent formats or structures that make information harder to find

  • Role in the Diátaxis Framework

    • Reference documentation serves users who need truth and certainty in their work
    • Provides firm platforms on which users can stand while they work
    • Gives users confidence to do their work effectively through reliable information
    • Complements but remains distinct from tutorials, how-to guides, and explanation
    • Addresses the information-oriented, theoretical knowledge quadrant of documentation needs

  • Real-World Analogy

    • Similar to information on food packaging or product specifications
    • Users expect standardized presentation of facts in a predictable format
    • Information should be reliable, consistent, and clearly separated from marketing or instructional content
    • The importance of reference is such that in many fields it's governed by standards or regulations