使用 Diataxis 建構高質量技術文件 - jneo8
======

{%hackmd @coscup/BkyL5IdFA %}

> 請從這裡開始

Slide: https://speakerdeck.com/jneo8/diataxis-2024-coscup

## Diátaxis 是什麼
Diátaxis 是一種協助你進行指導文件寫作的框架。

## Quality of a Document 文件品質好壞的定奪

### Functional Quality
- 準確性
- 實用性
- 關乎其運作本身的衡量方式
- 客觀的

### Deep Quality
- 閱讀者的主觀感受
- 撰寫者的Insight, Vision

Diátaxis 藉由指出 Functional Quality 的不足之處與短板，來幫助撰寫者在補上短版的過程中自然地達成 Deep Quality

## Craft 的四個象限
### Craft
是某種技術(Skill)的Domain
而指導文件是一種**Craft guide**。
指導文件依據應用場景(學習 - 應用)與描寫內容(行動 - 認知)可以分為四個象限。


- Action v.s. cognition
- Practice v.s. knowledge
- Practical v.s. theoratical
- 你的文件是教 實務 還是 理論
- 實務是主觀的、操作的、動作性的
- 理論是客觀的、抽象的、表述性的

- Acquisition v.s. application
- Study v.s. work
- Learn v.s. use
- 你的文件是讓使用者 洗澡時看的 還是 上場時看的

### 上場時看的實務 = How-to = 「攻略」
- 食譜、攻略、IKEA說明書
- goal oriented
- for user, be easy
- Omit unnecessary
- Address user's thinking and does
- Practical > completeness
- 製造心流
- Avoid context switch
- Anticipate and predict the reader

### 洗澡時看的實務 = Tutorial = 「教學」

- 幫助使用者學習，而不是完成某件事情
- 告訴學習者各個知識點跟方向，而不會把各個點連起來
- 學不會是作者的責任
- 越簡單越好
- 提供 reward / checkpoint, ASAP

### 上場時看的理論 = Reference = 「規格書」

- Technical description
- To describe and only to describe
- Truthful, certain, precise, structured
- 像個 map
- Reference 只會被用於查閱而非閱讀，因此 Reference 需要真實、正確、權威

### 洗澡時看的理論 = Explanation = 「簡談」

- 針對主題性的討論
- 你要解釋什麼
- 可以在洗澡的時候被閱讀就是好的 Explanation
- Give big picture, history, alternatives
- Establish connection
- Higher and wider