Monthly Archives: March 2020

整理 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等 … Continue reading →