## ENIGMAS --- ### Explanation and Reference #### Distinction - **Theory vs. Application**: - **Explanation**: Helps acquire knowledge (study). - **Reference**: Helps apply knowledge (work). #### Characteristics - **Reference**: - **Descriptive**: Lists, tables, factual information. - **Used During Work**: Consulted while performing tasks. - **Explanation**: - **Clarifying**: Provides understanding, background, and context. - **Used During Study**: Read to gain deeper knowledge. ### The Map of Needs #### Documentation Organization - **Generalized Structure**: Better to organize around user needs than product features. - **Diátaxis Map**: Four types of documentation - tutorials, how-to guides, references, explanations. #### User Needs - **Practitioner Focus**: Serving both theoretical grasp and practical application. - **Modes**: - **Study**: Acquiring skills and knowledge. - **Work**: Applying skills and knowledge. #### Axes of Knowledge - **Theory/Practice**: Divides documentation into theoretical knowledge and practical actions. - **Acquisition/Application**: Focuses on either acquiring or applying knowledge. #### Characteristics of Documentation - **Tutorials**: Introduce, educate, lead (learning-oriented). - **How-To Guides**: Guide, demonstrate (task-oriented). - **Reference**: State, describe, inform (information-oriented). - **Explanation**: Explain, clarify, discuss (understanding-oriented). ### The Cycle of Interaction #### User Journey - **Learning-Oriented Phase**: Begin with tutorials. - **Task-Oriented Phase**: Move to how-to guides. - **Information-Oriented Phase**: Consult references as needed. - **Explanation-Oriented Phase**: Reflect and understand with explanations. ### Towards a Theory of Quality in Documentation #### Functional Quality - **Attributes**: Accuracy, completeness, consistency, usefulness, precision. - **Independence**: These attributes are independent but collectively necessary. #### Deep Quality - **Attributes**: Feel-good use, flow, human fit, beauty, anticipation of user needs. - **Interdependence**: These attributes are interrelated and harder to measure. #### Recognizing Quality - **Functional Quality**: Objectively measured (accuracy, completeness). - **Deep Quality**: Subjectively experienced (flow, anticipation of needs). ### Diátaxis and Quality #### Functional vs. Deep Quality - **Functional Quality**: Can be analyzed and measured. - **Deep Quality**: Requires judgment and creativity. #### Application - **Expose Functional Quality Issues**: Diátaxis can highlight problems. - **Create Deep Quality**: Focus on user needs and flow. ### Diátaxis in Complex Hierarchies #### Structuring Documentation - **Basic Structure**: Simple, clear arrangement. - **Adding Hierarchy**: Grouping and organizing content for larger sets. - **Two-Dimensional Problems**: Addressing different user types or topic areas. - **User-First Thinking**: Structure documentation as it is experienced by the user. ### How to Use Diátaxis #### Pragmatic Use - **Guide, Not Plan**: Use Diátaxis principles to improve documentation iteratively. - **Work One Step at a Time**: Make small, incremental improvements. - **Organic Growth**: Let documentation develop naturally, ensuring completeness at each stage. #### Conclusion - **Diátaxis**: A practical approach to structuring and improving documentation based on user needs and phases of interaction. -----