需要進行分析
絕大多數技術文檔編寫者所做的第一件事情就是進行分析，而分析工作又可以分為兩種：對象分析以及任務分析。
對象分析
在進行對象分析的時候，你應該明確這份技術文檔是針對哪些人的，也就是什么樣的人會閱讀你的這份技術文檔。此外，你是否正在為公司里別的開發小組編寫應用編程接口(API)文件么？別的公司的開發人員是怎么樣做的？你應該去了解閱讀你所編寫技術文檔的那些人對于產品開發的內部過程了解多少，并且要知道公司內有哪些數據你可以使用，有哪些你不能使用？
有可能你正在為最終使用產品的用戶編寫技術性文檔。你要弄清楚這些用戶是使用計算機的菜鳥還是高手。這些用戶是否包括各種不同的類型，或者他們的背景是否要不盡相同呢？如果你對這些情況并不確定的話，這里有一些辦法能夠幫助你確定這些情況。和你公司里的服務組或者技術支持小組的成員就這些問題進行交談，這能夠幫助你通過他們的經驗來了解那些用戶的情況。閱讀有關此產品或者類似產品的新聞組以及郵件列表也可以讓你獲得有用的信息。你甚至可以在你們的網絡站點上進行問卷調查，或者直接把問卷分發到那些注冊過的用戶手里來了解情況。不過，在這么做的同時要讓這些人明白你是在為他們服務，這樣才會獲得更多的反饋。
任務分析
任務分析包括對讀者將會如何使用這些技術文檔進行分析。這份技術文檔是為了指導用戶如何安裝軟件產品而編寫的么？如果是這樣，你就要把精力集中在安裝過程中每一步驟的上面。是否是為了方便其他編程者而編寫的應用編程接口(API)文件？在這種情況下，你可能會需要一種基準格式來把應用編程接口(API)組件分解成邏輯排列的一些形式，這就讓需要閱讀這份文件的程序開發設計人員能夠輕松的從中獲得他們所需要的東西。
有些時候，把任務和相關參考文獻結合在一起是一種更好的辦法。在指導說明中可以包含參考文獻部分，并且這是作為獨立的內容而附加在指導說明上邊的。另一些好辦法是在這種指導說明中加入技巧、警告、注釋、表、數據以及其它的一些內容，這樣你就可以更生動的描述相關的內容，單純的動用大量的文字很容易讓讀者產生沉悶的感覺。
在技術文檔中加入圖形注釋
在技術文檔中加入技巧和警告內容是非常重要的，這樣能夠避免讓你的讀者產生和別的指導說明書或者參考材料混淆的感覺?？匆豢磩e人編寫的手冊或者技術說明書，你就能夠獲得大量的范例。典型的情況是，在你所添加的技巧和警告周圍加上邊框，或者用醒目的下劃線標注出來，對你的讀者來說都是很有幫助的。在文章中加入圖形也是一種好辦法，尤其是你在向讀者對某些事情進行警告的時候，圖形化的內容能夠讓你所警告的東西變得更清晰讓能夠產生深刻的印象。
注意技術文檔的措辭
對于技術性文檔來說，另一個重要的方面就是你的措辭。如果你的文檔所針對的對象是入門者或者沒有技術背景的人，你必須對你的這些讀者所擁有的知識進行分析，這是十分基本而且重要的。因為你不知道這些讀者對你所引用的縮寫詞匯是否真的明白。為了避免你的讀者對這些詞匯感到頭疼，一定要使用完整拼寫的詞匯，或者附加上一份縮寫詞匯表。有沒有更簡單的辦法呢？公司里負責市場的副總裁很可能并不清楚什么是API，但是如果你把API寫成“一套能夠幫助軟件設計人員讓他們開發的軟件能夠同我們所開發的軟件進行對話的工具”，這么寫看上去很費筆墨，但是，這樣卻能夠讓那些沒有技術背景的讀者很好的掌握API的含義。
對于那些專業的技術人員來說，你就可以使用那些專業術語了（也就是說，你可以使用堆棧、線程等等詞匯了），并且寫出這些詞匯的同時，并不需要你再特別的解釋一番。不過，如果你比不確定你所使用的一個縮寫詞是被廣泛認可的，那么，一定要在后邊把這個縮寫詞解釋清楚，并跟上完成的拼寫。不要過分使用那些冗長的詞匯以顯示你的詞匯量。盡量使用簡單的能夠說明問題的措辭；這么做更能夠給讀者留些深刻的印象，而不是讓你的讀者把時間浪費在查字典上。對于專業技術人員以及非專業技術人員來說，你都應該這么去編寫文件，這樣才能收到良好的效果。
保持文檔的前后一致性
最后，讓我們來看一看保持文檔內容一致性的重要性。你在文章的開始部分就應該決定使用米制長度單位還是使用英制長度單位。一些細微的地方你都應該做到前后統一，比如說，在文章前邊使用了5MB，那么在文章后面就不應該出現5 MB；你也得決定是使用5英尺還是使用5'，等等這些問題你必須都要注意。當你使用到變量的時候，會出現這種有趣的情況：在使用變量內容的時候，你是會使用“variable = definition of value”的形式，還是會使用“variable = example value”的形式？
另外一個需要注意的事情是你對字體的使用，因為用戶也許會需要做一些輸入的工作。一些人會使用等寬字體，例如Courier，來讓用戶輸入資料。還有要統一的是使用“下劃線”還是使用“粗體字”。具體使用哪一種形式這可以由你所在職業領域所習慣所決定，但是通常來說，只要在你的文章中保持前后用法的一致性就可以了。在你進行文件編寫的時候，邊上應該放上一張伸手可及的白紙，以便于你紀錄這些前后應該保持一致的用法以便于隨后查詢。
結論
能夠有一位專職的技術文檔編寫作者來創作你所需要的技術性文檔是非常好的事情，然而，有的時候出于某些原因，只有讓軟件開發設計人員自己動手來編寫這些技術文檔。雖然不是專業的技術文檔編寫者，但仍舊應該注意上面提到的那些問題，并且切實的把這些細節和注意事項都應用到技術文檔的編寫中去，這樣才能夠為你和你的用戶們編寫出隨時可用并且易于閱讀的技術文檔。
浙公網安備 33010802003509號
杭州講師網絡科技有限公司
