Diataxis-2024-COSCUP

Transcript

1. Diátaxis A system approach to technical documentation authoring.
2. Greek: Arrangement/Order/Disposition
3. Diataxis is an approach to quality in document
4. Agenda ➔ Introduce to Diataxis ◆ Quality in document ◆ Why Diataxis ➔ Types of the documents ◆ Tutorial ◆ How-to guides ◆ Reference ◆ Explanation ➔ Exercise ➔ More concept ➔ QA
5. jneo8 (j for James) github.com/jneo8 Engineer at Canonical
6. Why am I here?
7. What is quality in document?
8. Functional quality Deep quality
9. Functional Quality: Independent Accuracy Precision Usefulness Completeness Consistency Clear
10. Deep Quality: Subjective & Interdependent Accuracy Usefulness Consistency Completeness Precision Deep quality ➔ Feeling good to use ➔ Having fun ➔ Fitting human needs ➔ Being beautiful ➔ Anticipating the use
11. Is Dell XPS 13 a good laptop? Functional quality Deep quality Processor, Memory, Storage, Weight, Display, Power, Keyboard User experience? Nice for coding? Gaming experience? Independent characteristics Interdependent characteristics Objective Subjective Measured against the world Assessed against the human A condition of deep quality Conditional upon functional quality Aspects of constraint Aspects of liberation
12. Diataxis and Quality ➔ Good document feels good ➔ Diataxis cannot address functional quality in documentation ➔ It exposing lapses in functional quality ➔ It create deep quality ➔ Limits ◆ Principles, not formula
13. Why Diataxis works?
14. Diataxis create document for a craft
15. Craft - A domain of skill ➔ Programming ➔ Cooking ➔ Gaming ➔ Fly an airplane ➔ Sport ➔ Play an instrument ➔ Surgery ➔ Language ➔ …
16. Acquisition Application Action Cognition practical knowledge, knowing how, what we do theoretical knowledge, knowing that, what we think At study, concerned with acquiring them At work, concerned with applying the skill and knowledge of their craft When Practice/Knowledge
17. Acquisition Application Action Cognition GOALS Information UNDERSTANDING LEARNING
18. Acquisition Application Action Cognition HOW-TO GUIDES GOALS Information REFERENCE UNDERSTANDING EXPLANATION TUTORIALS LEARNING
19. 4 types of documents
20. A real word case HOW-TO GUIDES GOALS Information REFERENCE UNDERSTANDING EXPLANATION TUTORIALS LEARNING
21. Real word case: pytest & kubernetes
22. How-to Guides
23. A How-to guide is like ➔ Recipe ➔ Clinical manuals ➔ Game walkthrough ➔ Pilot Operating Handbook ➔ …
24. A How-to guide is Goal-oriented ➔ Directions that guide the reader ➔ How? ◆ What is the outcome? ◆ Action and only action • “To archive this, do that” ◆ Written from the perspective of the user, not of the machinery ◆ Omit the unnecessary • practical usability > completeness. • digression, explanation, teaching ◆ Address • how the user thinks • What the user does ◆ Seek flow • Avoid context switch • Anticipate the user
25. Tutorial
26. A tutorial is like • Hello world • Video game tutorial • Teaching children how to cooking • …
27. A tutorial is learning-oriented ➔ Help them learn, not get something done. ➔ Show the learner where they’ll be going ➔ An experience ◆ Try not to teach ◆ Point, line to Plane ◆ Repetition, Action, Small steps, Results early and Often ➔ Anti-pedagogical ◆ Abstraction, generalisation ◆ Explanation ◆ Choices ◆ Information ➔ Obligations of the teacher ◆ All the responsibility falls upon the teacher. ◆ Meaningful, successful, logical, usefully complete ➔ Reliability
28. Reference
29. A Reference is like • Ingredient List • Map • Pokedex • Engineering drawing • …
30. Reference guides are information-oriented ➔ Technical descriptions ➔ The only purpose ◆ Describe and only describe ➔ People consults, not reads ➔ Reference material is like a map. ➔ Styles ◆ explanation ◆ Truth, Certainty, Austere, and Authoritative ◆ Structured according to the structure of the machinery itself
31. Explanation
32. A Explanation is like • Gaming design theory • Movie analysis • Basic Principles of Sous Vide • …
33. Explanation is a understanding-oriented ➔ A discusive treatment of a subject ➔ To discuss ◆ bigger picture ◆ history ◆ choices/alternatives/possibilities ➔ Establishes connections ➔ Perspective of explanation ◆ higher and wider than that of the other not types • How-to guide -> user’s eye-level view • Reference material -> close-up view of the machinery ➔ Draw the boundaries ◆ Answer a Why question ➔ Can read in the bath.
34. Exercise 2 HOW-TO GUIDES 4 REFERENCE 3 EXPLANATION 1 TUTORIALS
35. 2 HOW-TO GUIDES 4 REFERENCE 3 EXPLANATION 1 TUTORIALS
36. 2 HOW-TO GUIDES 4 REFERENCE 3 EXPLANATION 1 TUTORIALS
37. 2 HOW-TO GUIDES 4 REFERENCE 3 EXPLANATION 1 TUTORIALS
38. 2 HOW-TO GUIDES 4 REFERENCE 3 EXPLANATION 1 TUTORIALS
39. 2 HOW-TO GUIDES 4 REFERENCE 3 EXPLANATION 1 TUTORIALS
40. 2 HOW-TO GUIDES 4 REFERENCE 3 EXPLANATION 1 TUTORIALS
41. 2 HOW-TO GUIDES 4 REFERENCE 3 EXPLANATION 1 TUTORIALS (Kubernetes services types)
42. 2 HOW-TO GUIDES 4 REFERENCE 3 EXPLANATION 1 TUTORIALS
43. 2 HOW-TO GUIDES 4 REFERENCE 3 EXPLANATION 1 TUTORIALS
44. 2 HOW-TO GUIDES 4 REFERENCE 3 EXPLANATION 1 TUTORIALS
45. 2 HOW-TO GUIDES 4 REFERENCE 3 EXPLANATION 1 TUTORIALS
46. The compass
47. Acquisition Application Action Cognition HOW-TO GUIDES GOALS Information REFERENCE UNDERSTANDING EXPLANATION TUTORIALS LEARNING
48. The compass If the content describes… serves the user’s serves the user’s Tutorial How to guide Reference Explanation Work Study Practical Steps Theoretical knowledge Work Study
49. How to use Diataxis?
50. Homework • How-to-guides vs Tutorial • Reference vs Explanation
51. We are hiring! https://canonical.com/careers/engineering
52. QA