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

需要進行分析

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

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

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

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

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

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

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

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

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

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

結(jié)論
　　能夠有一位專職的技術(shù)文檔編寫作者來創(chuàng)作你所需要的技術(shù)性文檔是非常好的事情，然而，有的時候出于某些原因，只有讓軟件開發(fā)設(shè)計人員自己動手來編寫這些技術(shù)文檔。雖然不是專業(yè)的技術(shù)文檔編寫者，但仍舊應(yīng)該注意上面提到的那些問題，并且切實的把這些細(xì)節(jié)和注意事項都應(yīng)用到技術(shù)文檔的編寫中去，這樣才能夠為你和你的用戶們編寫出隨時可用并且易于閱讀的技術(shù)文檔。

該文章在 2012/2/14 9:46:26 編輯過