整理 https://www.divio.com/blog/documentation/ 對於software documentation的觀點
該篇blog文主要解釋軟體文件需要具備的幾個部分(從他的文章內容來看，這邊的軟體比較接近library)
- tutorial
- guide (how-to guide)
- explanation
- reference
一個好的文件，需要區分這四個部分。主要原因在這四個部分所針對的對象不同，目的也不同。
tutorial的重點在new comer，第一次接觸這個軟體/library的人要如何入門。文章提到這常也是軟體是否成功的關鍵-將new comer變成user的關鍵。如果使用的人覺得學習障礙很高，很可能就不用了。. “A bad or missing tutorial will prevent your project from acquiring new users.”
guide是topic based，針對一個topic透過一系列的步驟完成，在文章中他用cook recipe來形容
explanation比較像是背景說明，在一般library文件我們常會看到design rationale可以算在這類
reference主要在information細節整理，可以想成是dictionary
另外文章也說明 區分project documentation和software documentation。有很多文件是算在project documentation:例如change log等
寫tutorial可以以ALLOW THE USER TO LEARN BY DOING為方向。軟體/library作為工具，要讓使用者了解這是什麼、能達成什麼，最快的方式就是提供範例步驟，儘管很多東西是需要理論背景建構，但是為了能夠先抓住新來使用者的注意，降低學習門檻還是有必要的。因此，範例最好是短、可理解、可即時得到結果。當然，在tutorial裡的範例本身也要有意義才行。
該文章提到，在tutorial裡的重點擺在比較具體的概念，從學習的角度-具體到抽象。並且盡量不做不必要的解釋，在tutorial階段不需要知道的東西不必提及。
guide是goal oriented，針對某個主題或問題(problem)，提供一系列的步驟完成解決。用cooking來舉例，完成tutorial的使用者已經懂得基本的料理方法與料理器具的使用。但是煮出某道菜，可能不是那麼直觀，需要將不同已經習得的方法進行整合，在這個階段，也可以假設guide的讀者是有具備一定基礎的使用者，不須針對一些基礎的操作或概念重述
guide強調是步驟而不是概念，解決問題強調的是方法， 如果一個問題有不同的方式處理，可以放在guide說明，而非tutorial。另外，文章提及 “Tutorials need to be complete, end-to-end guides; how-to guides do not.”
tutorial強調的是全面性的介紹，guide強調是特定topic。同時，guide(how-to guide)是要講解 “How to —-” 而非”What is —-“
reference是information-oriented.information-oriented，
不介紹基本概念，並且用詞要精確 “Reference material should be austere and to the point.”
文章提及，reference documentation維持和codebase相同的structure有助於user對照code。 另外也要保持語法用法符號格式的一致性。
reference做的是描述，而非how to或是concept。
“Anything else (explanation, discussion, instruction, speculation, opinion) is not only a distraction, but will make it harder to use and maintain. “
explanation重點在understanding-oriented，可以是discussions，或是提供背景說明，例如為什麼這樣設計library design decisions以及 historical reasons, technical constraints等等。
在該文章最後面說明，事實上，上述的四個面向各有重疊的部分。例如tutorial和how-to guide都描述了一些具體的步驟， reference和explanation都關心比較理論性的部分，而tutorial和explanation都比較適合做為研讀(study)而非實際工作時用到的文件。
文件的形成，常常無法一開始到位。可以採用漸進式的作法，慢慢地往上述四個面向演進。