如何寫好軟體文檔

標籤：文檔   技術文檔   

今天看到一篇介紹寫作技術文檔的文章，試著翻譯了一下，翻得不好，請大家幫忙改正。本文如下：
 
我不知道是不是有人會將閱讀或書寫技術文檔當做愛好。雖然很討厭這樣做，但是通常為瞭解決問題或介紹一個技術產品，我們不得不去做這些事情。

要想寫好文檔很難。技術文檔有幾種形式：基本概覽，進階概覽，一步一步的示範，自動產生的文檔，等等。考慮下不同使用者對你的文檔的需求情況：不同的需求，不同的技術，不同的學習風格。你將會發現，沒有一種格式能同時適應所有人。

受眾情況

在寫項目文檔的時候，你首先要考慮到的是讀者。終端使用者首先需要的是一份入門指南。儘管一些技術概念可能會提到，但是重點應放在使用者介面，而不是後台。如果是程式員，他可能會想得到更多的資訊：程式運行原理，代碼的實現，怎樣對代碼進行擴充，等等。為部分使用者寫的文檔不應當影響到另一部分使用者的閱讀，你可以考慮寫兩份單獨的文檔，使用者使用手冊和技術文檔。

幾種不同類型的文檔

Jacob Kaplan-Moss在他的怎樣寫好文檔的指南中，他提到了三種文檔：教程，專題指南和參考指南。

教程：教程是很重要的，因為這往往是使用者在使用新的工具時得到的第一印象。我們之前寫到過，有許多不同的工具可以幫你寫好教程。如果你想寫的話，Kaplan-Moss建議你寫得簡單快速一些，但是不要太簡單了，可以做一個示範，為每一步驟添加相關的。

專題指南：Kaplan-Moss說這是文檔的主要內容。雖然教程提供了一個高層次的概念，但是專題指南可以讓感興趣的人深入學習，內容一定要詳盡。Kaplan-Moss提到，一般來說，圖書要勝過官方文檔，但是後者的一個優點是隨時更新。

參考指南：參考指南是為那些已經入門但是還需要更多資訊的使用者準備的。為那些已經知道怎樣使用API，但是需要尋找確切的函數參數或詳細設定資訊的使用者定製的。要指出的是，參考指南是無法由教程和普通指南替代的。自動產生的文檔只能起一個引導作用，如果沒有額外的寫作，編輯和組織，它是不可能解決大家的問題的。


雖然這是“技術寫作”，但是這並不意味著你應該放棄文采，文法和拼字檢查。至少得檢查一下文法和拼字吧。


原文連結： http://www.readwriteweb.com/start/2010/08/tips-for-writing-good-document.php

如何寫好軟體文檔