技術(shù)文檔寫(xiě)作技巧

最近在公司內(nèi)部審查（Review）一篇詳細(xì)設(shè)計(jì)文檔時(shí)，對(duì)于文檔作者所寫(xiě)的文檔覺(jué)得很多地方需要改進(jìn)。對(duì)于其中所存在的值得提高的地方，我想不是我們中國(guó)軟件行業(yè)的個(gè)別問(wèn)題，相反，存在一定的普遍性。以下我列出了幾個(gè)值得提高的地方。

1） 文檔的格式上存在不一致性的問(wèn)題。格式有時(shí)是這樣，有時(shí)是那樣。一篇好的文檔我想不光是內(nèi)容寫(xiě)得好，其格式是很重要的一部分。試想，如果我們拿到了一篇格 式上寫(xiě)得亂七八糟的文檔，這一第一印象會(huì)影響我們的閱讀心情嗎？好的文檔應(yīng)當(dāng)是從頭到尾保持格式的一致性，這不僅僅是一種美，更是專(zhuān)業(yè)性的一種表現(xiàn)。

2） 寫(xiě)文檔的作者不能很好的站在讀者的角度去思考。要寫(xiě)出一篇好的支持文檔，作者應(yīng)當(dāng)站在讀者的角度上去寫(xiě)。這簡(jiǎn)單的一句話(huà)，要操作起來(lái)，將其做好，還真不是 一件容易的事。在寫(xiě)文檔時(shí)，如果不站在讀者的角度去思考，很容易寫(xiě)出一篇“自己一看覺(jué)得清清楚楚，別人一看卻糊里糊涂”的文檔。

3）文檔求長(zhǎng)不求 精。一說(shuō)到寫(xiě)文檔，我不知是否有人將“文檔應(yīng)當(dāng)長(zhǎng)”當(dāng)作是文檔的必要屬性。對(duì)于這一點(diǎn)，我想正確的態(tài)度是：求精不求長(zhǎng)。一篇好的文檔，應(yīng)當(dāng)寫(xiě)得簡(jiǎn)練易懂。 寫(xiě)文檔的目的是什么？是為了讓別人明白我們所要說(shuō)明的問(wèn)題，要說(shuō)明問(wèn)題，并不需要一定將其寫(xiě)得長(zhǎng)。一篇精煉的文檔也意味著效率，即讀者花很少的時(shí)間就明白 我們想要表達(dá)的問(wèn)題是什么。當(dāng)然，從作者的角度來(lái)看，要寫(xiě)一篇精煉的文檔，那得花更多的時(shí)間去斟酌。

4）圖太少。有圖不是一篇好文檔的必要條件，但在不少情況下，用一幅圖能很好的表達(dá)我們的思想，不是有那么一句話(huà)嗎“好圖勝過(guò)千言萬(wàn)語(yǔ)”，適當(dāng)?shù)牟捎靡恍﹫D，一方面能為文檔增色，另一方面也能更好的向讀者傳達(dá)我們的意圖。

好了，值得提高的點(diǎn)也提出來(lái)了，如何去做好呢？我想下面是我所能想到的一些方法，在此，將與上面的提高點(diǎn)一一對(duì)應(yīng)進(jìn)行闡述。

1）對(duì)于格式問(wèn)題，找一篇自己覺(jué)得格式不錯(cuò)的文檔進(jìn)行模仿，并將其做成一個(gè)模板，每次寫(xiě)作時(shí)以這一模板為基礎(chǔ)。

2） 寫(xiě)完以后，假設(shè)自己是讀者多次閱讀自己的文檔。這一點(diǎn)要做好還是很難的，因?yàn)椋�我們很難完全站在讀者的角度去讀自己寫(xiě)的文檔，我們不知道自己所知的哪些東 西是讀者所不知的，即很難界定與讀者知識(shí)不對(duì)稱(chēng)的分界點(diǎn)。為了提高這一點(diǎn)，我想我們寫(xiě)文檔時(shí)，應(yīng)當(dāng)多問(wèn)自己一些問(wèn)題，比如，讀者具有與我一樣的知識(shí)和經(jīng)驗(yàn) 嗎？如果沒(méi)有，我應(yīng)當(dāng)寫(xiě)哪些以彌補(bǔ)這種信息的不對(duì)稱(chēng)性呢？我寫(xiě)的這篇文檔是基于一定的假設(shè)嗎？如果是，是否應(yīng)當(dāng)將這一假設(shè)在文檔中交代清楚呢？我所寫(xiě)的內(nèi) 容是否都在支持文檔的主題呢？是否存在正交問(wèn)題（即答非所問(wèn)的問(wèn)題）？等等。

3）在文檔寫(xiě)完后多問(wèn)一問(wèn)自己，這篇文檔還能寫(xiě)得更簡(jiǎn)單嗎？是否可以將一些文字省去并用一幅圖取而代之以達(dá)到使其簡(jiǎn)練的目的呢？不防時(shí)刻對(duì)自己說(shuō)，簡(jiǎn)單也是一種美！

4） 學(xué)習(xí)（并精通）一些行業(yè)所需的圖形語(yǔ)言和工具，并加以運(yùn)用。比如，我們軟件行業(yè)的UML就是很好的一種表達(dá)語(yǔ)言，且隨著UML的發(fā)展，其表達(dá)能力更加的強(qiáng) 大。目前，業(yè)內(nèi)有很我UML的工具，找一個(gè)不錯(cuò)的就行了，比如Visual

Paradigm的UML工具就不錯(cuò)，工具其實(shí)只是一種工具，關(guān)鍵是掌握UML。只有我們很好的掌握一種圖形語(yǔ)言，我們才有可能隨時(shí)加以運(yùn)用，從而為我們 的技術(shù)文檔服務(wù)。當(dāng)然，像Microsoft的Viso也是不錯(cuò)的繪圖工具，這要看我們想表達(dá)的是什么，從而加以靈活運(yùn)用各種工具。

至 此就好了嗎？不，還有很重要的一點(diǎn)是：我們需要在思想上做一些改變，這種改變是什么呢？那就是：寫(xiě)出一篇好的技術(shù)文檔是一個(gè)專(zhuān)業(yè)軟件工程師的必要素養(yǎng)！我 們必須拋棄那種軟件工程師只要能寫(xiě)出漂亮的代碼就行了的思想，而是要將“寫(xiě)好每一篇技術(shù)文檔是專(zhuān)業(yè)軟件工程師的必要素養(yǎng)”這一句話(huà)深入到我們的骨髓當(dāng)中 去，只有這樣，我們所寫(xiě)的技術(shù)文檔才會(huì)越來(lái)越好、才會(huì)越來(lái)越專(zhuān)業(yè)。

【技術(shù)文檔寫(xiě)作技巧】相關(guān)文章：

word無(wú)法讀取文檔文檔可能損壞的解決方法06-21

考勤制度文檔04-13

收入證明excel文檔05-06

收入證明文檔05-06

我的文檔收入證明05-06

校本研修總結(jié)文檔03-18

五四活動(dòng)方案文檔03-21

總結(jié)及改進(jìn)措施文檔03-19

電梯應(yīng)急預(yù)案文檔03-21