一般情況下，每一個(gè)開發(fā)小組都擁有一個(gè)或者更多的專業(yè)技術(shù)文檔編寫者，這些編寫者負(fù)責(zé)為他們的產(chǎn)品編寫出相關(guān)的技術(shù)文檔。然而，并不是所有的公司能擁有專職的技術(shù)文檔編寫者。如果你必須編寫出和你的軟件產(chǎn)品聯(lián)系在一起的技術(shù)文檔的時(shí)候，你應(yīng)該在你的腦子里記住下面的這些必須進(jìn)行的事情。

需要進(jìn)行分析

　　絕大多數(shù)技術(shù)文檔編寫者所做的第一件事情就是進(jìn)行分析，而分析工作又可以分為兩種：對(duì)象分析以及任務(wù)分析。

對(duì)象分析

　　在進(jìn)行對(duì)象分析的時(shí)候，你應(yīng)該明確這份技術(shù)文檔是針對(duì)哪些人的，也就是什么樣的人會(huì)閱讀你的這份技術(shù)文檔。此外，你是否正在為公司里別的開發(fā)小組編寫應(yīng)用編程接口(API)文件么？別的公司的開發(fā)人員是怎么樣做的？你應(yīng)該去了解閱讀你所編寫技術(shù)文檔的那些人對(duì)于產(chǎn)品開發(fā)的內(nèi)部過(guò)程了解多少，并且要知道公司內(nèi)有哪些數(shù)據(jù)你可以使用，有哪些你不能使用？

　　有可能你正在為最終使用產(chǎn)品的用戶編寫技術(shù)性文檔。你要弄清楚這些用戶是使用計(jì)算機(jī)的菜鳥還是高手。這些用戶是否包括各種不同的類型，或者他們的背景是否要不盡相同呢？如果你對(duì)這些情況并不確定的話，這里有一些辦法能夠幫助你確定這些情況。和你公司里的服務(wù)組或者技術(shù)支持小組的成員就這些問(wèn)題進(jìn)行交談，這能夠幫助你通過(guò)他們的經(jīng)驗(yàn)來(lái)了解那些用戶的情況。閱讀有關(guān)此產(chǎn)品或者類似產(chǎn)品的新聞組以及郵件列表也可以讓你獲得有用的信息。你甚至可以在你們的網(wǎng)絡(luò)站點(diǎn)上進(jìn)行問(wèn)卷調(diào)查，或者直接把問(wèn)卷分發(fā)到那些注冊(cè)過(guò)的用戶手里來(lái)了解情況。不過(guò)，在這么做的同時(shí)要讓這些人明白你是在為他們服務(wù)，這樣才會(huì)獲得更多的反饋。

任務(wù)分析

　　任務(wù)分析包括對(duì)讀者將會(huì)如何使用這些技術(shù)文檔進(jìn)行分析。這份技術(shù)文檔是為了指導(dǎo)用戶如何安裝軟件產(chǎn)品而編寫的么？如果是這樣，你就要把精力集中在安裝過(guò)程中每一步驟的上面。是否是為了方便其他編程者而編寫的應(yīng)用編程接口(API)文件？在這種情況下，你可能會(huì)需要一種基準(zhǔn)格式來(lái)把應(yīng)用編程接口(API)組件分解成邏輯排列的一些形式，這就讓需要閱讀這份文件的程序開發(fā)設(shè)計(jì)人員能夠輕松的從中獲得他們所需要的東西。

　　有些時(shí)候，把任務(wù)和相關(guān)參考文獻(xiàn)結(jié)合在一起是一種更好的辦法。在指導(dǎo)說(shuō)明中可以包含參考文獻(xiàn)部分，并且這是作為獨(dú)立的內(nèi)容而附加在指導(dǎo)說(shuō)明上邊的。另一些好辦法是在這種指導(dǎo)說(shuō)明中加入技巧、警告、注釋、表、數(shù)據(jù)以及其它的一些內(nèi)容，這樣你就可以更生動(dòng)的描述相關(guān)的內(nèi)容，單純的動(dòng)用大量的文字很容易讓讀者產(chǎn)生沉悶的感覺(jué)。

在技術(shù)文檔中加入圖形注釋

　　在技術(shù)文檔中加入技巧和警告內(nèi)容是非常重要的，這樣能夠避免讓你的讀者產(chǎn)生和別的指導(dǎo)說(shuō)明書或者參考材料混淆的感覺(jué)。看一看別人編寫的手冊(cè)或者技術(shù)說(shuō)明書，你就能夠獲得大量的范例。典型的情況是，在你所添加的技巧和警告周圍加上邊框，或者用醒目的下劃線標(biāo)注出來(lái)，對(duì)你的讀者來(lái)說(shuō)都是很有幫助的。在文章中加入圖形也是一種好辦法，尤其是你在向讀者對(duì)某些事情進(jìn)行警告的時(shí)候，圖形化的內(nèi)容能夠讓你所警告的東西變得更清晰讓能夠產(chǎn)生深刻的印象。

注意技術(shù)文檔的措辭

　　對(duì)于技術(shù)性文檔來(lái)說(shuō)，另一個(gè)重要的方面就是你的措辭。如果你的文檔所針對(duì)的對(duì)象是入門者或者沒(méi)有技術(shù)背景的人，你必須對(duì)你的這些讀者所擁有的知識(shí)進(jìn)行分析，這是十分基本而且重要的。因?yàn)槟悴恢肋@些讀者對(duì)你所引用的縮寫詞匯是否真的明白。為了避免你的讀者對(duì)這些詞匯感到頭疼，一定要使用完整拼寫的詞匯，或者附加上一份縮寫詞匯表。有沒(méi)有更簡(jiǎn)單的辦法呢？公司里負(fù)責(zé)市場(chǎng)的副總裁很可能并不清楚什么是API，但是如果你把API寫成“一套能夠幫助軟件設(shè)計(jì)人員讓他們開發(fā)的軟件能夠同我們所開發(fā)的軟件進(jìn)行對(duì)話的工具”，這么寫看上去很費(fèi)筆墨，但是，這樣卻能夠讓那些沒(méi)有技術(shù)背景的讀者很好的掌握API的含義。

　　對(duì)于那些專業(yè)的技術(shù)人員來(lái)說(shuō)，你就可以使用那些專業(yè)術(shù)語(yǔ)了（也就是說(shuō)，你可以使用堆棧、線程等等詞匯了），并且寫出這些詞匯的同時(shí)，并不需要你再特別的解釋一番。不過(guò)，如果你比不確定你所使用的一個(gè)縮寫詞是被廣泛認(rèn)可的，那么，一定要在后邊把這個(gè)縮寫詞解釋清楚，并跟上完成的拼寫。不要過(guò)分使用那些冗長(zhǎng)的詞匯以顯示你的詞匯量。盡量使用簡(jiǎn)單的能夠說(shuō)明問(wèn)題的措辭；這么做更能夠給讀者留些深刻的印象，而不是讓你的讀者把時(shí)間浪費(fèi)在查字典上。對(duì)于專業(yè)技術(shù)人員以及非專業(yè)技術(shù)人員來(lái)說(shuō)，你都應(yīng)該這么去編寫文件，這樣才能收到良好的效果。

保持文檔的前后一致性

　　最后，讓我們來(lái)看一看保持文檔內(nèi)容一致性的重要性。你在文章的開始部分就應(yīng)該決定使用米制長(zhǎng)度單位還是使用英制長(zhǎng)度單位。一些細(xì)微的地方你都應(yīng)該做到前后統(tǒng)一，比如說(shuō)，在文章前邊使用了5MB，那么在文章后面就不應(yīng)該出現(xiàn)5 MB；你也得決定是使用5英尺還是使用5'，等等這些問(wèn)題你必須都要注意。當(dāng)你使用到變量的時(shí)候，會(huì)出現(xiàn)這種有趣的情況：在使用變量?jī)?nèi)容的時(shí)候，你是會(huì)使用“variable = definition of value”的形式，還是會(huì)使用“variable = example value”的形式？

　　另外一個(gè)需要注意的事情是你對(duì)字體的使用，因?yàn)橛脩粢苍S會(huì)需要做一些輸入的工作。一些人會(huì)使用等寬字體，例如Courier，來(lái)讓用戶輸入資料。還有要統(tǒng)一的是使用“下劃線”還是使用“粗體字”。具體使用哪一種形式這可以由你所在職業(yè)領(lǐng)域所習(xí)慣所決定，但是通常來(lái)說(shuō)，只要在你的文章中保持前后用法的一致性就可以了。在你進(jìn)行文件編寫的時(shí)候，邊上應(yīng)該放上一張伸手可及的白紙，以便于你紀(jì)錄這些前后應(yīng)該保持一致的用法以便于隨后查詢。

結(jié)論

　　能夠有一位專職的技術(shù)文檔編寫作者來(lái)創(chuàng)作你所需要的技術(shù)性文檔是非常好的事情，然而，有的時(shí)候出于某些原因，只有讓軟件開發(fā)設(shè)計(jì)人員自己動(dòng)手來(lái)編寫這些技術(shù)文檔。雖然不是專業(yè)的技術(shù)文檔編寫者，但仍舊應(yīng)該注意上面提到的那些問(wèn)題，并且切實(shí)的把這些細(xì)節(jié)和注意事項(xiàng)都應(yīng)用到技術(shù)文檔的編寫中去，這樣才能夠?yàn)槟愫湍愕挠脩魝兙帉懗鲭S時(shí)可用并且易于閱讀的技術(shù)文檔。