目標(biāo)讀者
本課程的目標(biāo)讀者為已完成技術(shù)寫作 第一課，但是仍然渴望進(jìn)行更多寫作培訓(xùn)的人員。如果你沒有接受過任何技術(shù)寫作的培訓(xùn)，最好先看一下第一課能容。
學(xué)習(xí)目標(biāo)
這節(jié)課側(cè)重于技術(shù)寫作中的幾個中間主題，學(xué)習(xí)完本課程之后，將收獲如下的知識：
從幾種不同的策略中選擇一種編寫第一稿的策略，以及第二稿、第三稿的其他策略。
使用多種技術(shù)來檢測寫作中的錯誤。
學(xué)會組織大型的文檔。
介紹文檔的范圍和所有先決條件。
寫下清晰的圖形標(biāo)題。
在技術(shù)插圖中選擇適當(dāng)?shù)男畔⒚芏取?/p>
將讀者的注意力集中在插圖上。
通過圖片建立上下文。
有效的修改技術(shù)插圖。
創(chuàng)建有用、準(zhǔn)確、簡潔，清晰，可重用和注釋良好的代碼，用來演示一系列的復(fù)雜性。
標(biāo)示不同的文檔類型。
描述所有的內(nèi)容。
體諒初學(xué)者，并為他們編寫教程。
成為一名優(yōu)秀的工程師或者優(yōu)秀的技術(shù)作家都需要花費多年的專注實踐，這門課程能提高你的寫作水平，但不會立即使你成為一個出色的作家。
自我編輯
換位思考：
嘗試從讀者的角度閱讀文檔，確保文檔目的是明確的；并考慮好不同的角色所擁有的知識儲備。
然后從作者的角度閱讀文檔，確保你做的假設(shè)有用，還可以提供資源的鏈接。
最后請注意，過分依賴角色，會導(dǎo)致文檔過于狹隘，而無法對大多數(shù)讀者有用。
大聲讀出來：
- 自己大聲的朗讀或者使用屏幕閱讀器朗讀，來聽取尷尬的措辭，冗長的句子或其他不自然的內(nèi)容。
編寫每一搞的策略：
- 編寫完每一個版本之后，先放邊上一個小時，然后再回來閱讀一遍，總會發(fā)現(xiàn)有可以改進(jìn)的地方，推薦做三遍。
檢查寫作中的錯誤：
邀請某人查看你的文檔，并給你具體的，建設(shè)性意見。
閱讀的人不一定是同行，但是最好熟悉你遵循的文檔風(fēng)格。
寫一個大型文檔
使用以下策略可以幫助你們撰寫大型文檔：
選擇編寫單個大型文檔或一組簡短文檔。
把簡短文檔整理為一個大型文檔。
給大型文檔添加導(dǎo)航。
逐步暴露信息。
什么時候?qū)懘笪臋n：
當(dāng)你的閱讀對象是剛?cè)腴T的讀者時，寫操作指南、入門概述和概念性指南通常能以短文的形式提供更好的作用。
當(dāng)已經(jīng)對工具和主題有一定經(jīng)驗的讀者，寫深入教程，最佳實踐指南和命令行參考頁可以作為更長的文檔使用。
好的教程能可以依靠敘述來引導(dǎo)讀者完成較長文檔中的一系列相關(guān)任務(wù)。
寫較長文檔的方法：
創(chuàng)建大綱和起草宣言。
完成初稿之后，可以更具概述和簡介對其進(jìn)行復(fù)審。
編寫大綱的實用技巧：
在要求讀者執(zhí)行任務(wù)前，先解釋為什么要執(zhí)行此任務(wù)。
將大綱的每個步驟限制為描述概念或完成特定任務(wù)。
構(gòu)造輪廓，以便文檔在與讀者最相關(guān)時引入信息。
在起草前，先與貢獻(xiàn)者共享大綱內(nèi)容。
可以提供一個基本信息來介紹文檔：
說明文檔涵蓋的內(nèi)容。
希望讀者具備哪些知識儲備。
說明文檔沒有涵蓋那些內(nèi)容。
為文檔添加目錄，可確保讀者能快速的找到所需要的內(nèi)容，清晰的目錄包括：
簡介和摘要
主題清晰
有助于用戶理解的標(biāo)題和子標(biāo)題
提示用戶在目錄中的位置
可以通過目錄能跳轉(zhuǎn)到相關(guān)位置
有下一步學(xué)習(xí)的鏈接
在每個標(biāo)題下都進(jìn)行簡短的介紹，避免在標(biāo)題后面馬上放入下一級標(biāo)題。
圖片
在插入圖之前寫標(biāo)題會很有幫助，然后，插入能說明標(biāo)題的圖片
圖片中好的標(biāo)題應(yīng)該具有下面的特征：
他們很簡短，通常只是幾句話。
說明了重點。
能吸引讀者的注意力。
考慮以下三個圖形，每個圖形使用相同的標(biāo)題。
標(biāo)題A。單鏈接列表包含內(nèi)容和指向下一個節(jié)點的指針。
標(biāo)題B。單鏈接列表包含內(nèi)容和指向下一個節(jié)點的指針。
標(biāo)題C。單鏈接列表包含內(nèi)容和指向下一個節(jié)點的指針。
上述三個標(biāo)題中標(biāo)題C是最具啟發(fā)性的，標(biāo)題清晰的描述了圖片的功能。
如下圖片中的信息量不要過大。
如上圖的復(fù)雜性就會讓很多讀者望而卻步，就像避免過長的句子一樣，請盡量避免較復(fù)雜的圖片。
將復(fù)雜的圖片變?yōu)檫B貫且有用的訣竅是將復(fù)雜的系統(tǒng)組織成子系統(tǒng)。
圖4.分為三個子系統(tǒng)的復(fù)雜系統(tǒng)。
顯示大圖之后再分別提供每個子系統(tǒng)的圖片。
圖5.復(fù)雜系統(tǒng)的一個子系統(tǒng)的擴(kuò)展細(xì)節(jié)。
畫圖工具
-
創(chuàng)建示例代碼
代碼仍然是技術(shù)人最喜歡讀的，好的代碼通常是最好的文檔。
好的代碼樣本是正確、簡潔，你的讀者可以快速理解它們，并能以最小的代價重復(fù)使用它們。
正確
示例代碼應(yīng)該滿足下面條件：
代碼構(gòu)建沒有錯誤。
能按要求進(jìn)行執(zhí)行。
要做好生產(chǎn)使用的準(zhǔn)備，比如，代碼不能有安全漏洞。
遵循語言的約定。
簡潔
示例代碼應(yīng)該簡短，僅包括基本組件，不相關(guān)的代碼可能會使你的讀者分散注意力。但是，也不要用錯誤的做法來縮短你的代碼，在正確和簡短之間，我們更看重正確性。
