初學者的技術寫做：技術博客基礎知識A-Z指南

若是你喜歡寫做和技術，技術寫做多是一個適合你的職業。若是你喜歡技術，但又不是真的成天喜歡編碼，也能夠作一些別的事情。

若是你喜歡經過教導他人來學習，爲開源項目作出貢獻，並教導他人如何作到這一點，或者基本上喜歡經過你的寫做以簡單的方式解釋複雜的概念，技術寫做也可能適合你。

讓咱們深刻了解基礎知識，瞭解你在開始技術寫做時應該知道和考慮的問題。

什麼是技術寫做？

技術寫做是一門藝術，提供細節導向的指導，以幫助用戶理解特定的技能或產品。

技術做者是寫這些說明的人，也稱爲技術文檔或教程。這可能包括用戶手冊、在線支持文章或者程序員/API開發者的內部文檔。

技術寫做者的交流方式是將技術信息呈現給讀者，使讀者可以將這些信息用於預期的目的。

技術寫做的好處

技術寫做者也是是終身學習者。因爲這份工做須要用簡單而直接的術語來表達複雜的概念，因此你必須精通你所寫的領域，或者願意學習它。

這很好，由於每研究和編寫一份新的技術文檔，你就會成爲該領域的專家。

技術寫做還能讓你更好地理解用戶的感覺，它幫助你更多地關注讀者或用戶對產品的感覺，而不是你的想法。

你也能夠經過爲組織撰稿來賺錢。下面是一些付錢給你爲他們寫文章的機構，好比Smashing雜誌、AuthO、Twilio和Stack Overflow。

除此之外，你還能夠爲開源社區作貢獻，參與Google Season of Docs和Outreachy等付費開源項目。

你也能夠把技術寫做做爲一個全職職業——不少公司都須要有這些技能的人。

做爲技術做家必須具有的技能

瞭解正確的英語用法

在你考慮寫做以前，有必要掌握好英語、時態、拼寫和基本語法。你的讀者不但願讀到一篇充滿錯誤語法和糟糕詞彙選擇的文章。

知道如何清楚、簡單地解釋事物

知道如何實現功能並不必定意味着你能夠與其餘人清楚地交流該過程。

爲了成爲一名優秀的老師，你必須具備同理心，可以以適合你的目標受衆的方式教授或描述術語。

若是你不能向六歲的孩子解釋它，那麼你本身也不瞭解。——艾爾伯特·愛因斯坦

具有必定的寫做技巧‌‌

我相信，做家是天生的，而不是後天的，而你只有經過實際寫做才能學會如何寫做。

你可能永遠都不知道你有寫做的能力，直到你把筆放到紙上。而要想知道本身是否有必定的寫做能力，只有一個辦法，那就是經過寫做。

因此我鼓勵你從今天開始寫做。你能夠選擇從我在本節中列出的任何一個平臺開始，以擴展你的寫做能力。

固然，擁有一些技術領域的經驗也是巨大的好處。

技術寫做過程

分析並瞭解你的讀者是誰

當你在寫一篇技術文章時，要考慮的最大因素是你的預期/指望受衆。它應該始終在你的腦海中佔據最重要的位置。

一個好的技術寫做者會根據讀者的語境來寫做。舉個例子，好比說你要寫一篇針對初學者的文章。重要的是，不要假設他們已經知道某些概念。

你能夠在文章開頭概述任何須要的先決條件。這將確保你的讀者在直接進入你的文章以前已經（或可以得到）他們所須要的知識。

你還能夠加入有用資源的連接，這樣你的讀者只需點擊一下就能得到他們須要的信息。

爲了知道你是爲誰而寫，你必須儘量多地收集關於誰將使用該文件的信息。

重要的是要知道你的讀者是否在該領域有專業知識，是否這個話題對他們來講是全新的，或者他們是否介於二者之間。

你的讀者也會有他們本身的指望和需求。當讀者開始閱讀文檔時，你必須肯定他們在尋找什麼，以及他們將從中得到什麼。

要了解你的讀者，請在開始寫做以前先問本身如下幾個問題：

• 個人讀者是誰？
• 他們須要什麼？
• 他們將在哪裏閱讀？
• 他們何時閱讀？
• 他們爲何要閱讀？
• 他們將如何閱讀？

這些問題還能幫助你思考讀者在閱讀你的寫做時的體驗，這一點咱們如今要多說幾句。

考慮用戶體驗

用戶體驗在技術文檔中和在網絡上的任何地方同樣重要。

既然你知道了你的受衆和他們的需求，就要記住文檔自己是如何爲他們的需求服務的。很容易忽略讀者實際會如何使用文檔。

寫做時，不斷後退一步，把本身當成讀者來看待文檔。問問本身： 它是可訪問的嗎？你的讀者將如何使用它？他們什麼時候會使用它？是否易於閱讀？

目的是編寫一個對讀者有用和可用的文檔。

計劃你的文檔

記住你的用戶是誰，而後你就能夠對你的文檔進行構思和規劃。

這個過程包括許多步驟，咱們如今將繼續進行。

對該主題進行深刻研究

在規劃你的文檔時，你必須研究你要寫的主題。有大量的資源只需在谷歌上搜索一下就能夠供你消費，並從中得到更深的看法。

不要試圖從別人的做品或文章中摘錄下來，而後看成本身的做品，由於這就是抄襲。相反，將這些資源做爲你工做的參考和想法。

儘量多地使用谷歌，從研究期刊、書籍或新聞中獲取事實和數據，儘量多地收集有關你的主題的信息。而後你就能夠開始作一個大綱了。

作一個大綱

在擴展文檔內容以前先列出提綱，這有助於你更專一地寫做。它還可讓你組織你的思路，實現你的寫做目標。

提綱還能夠幫助你肯定你但願讀者從文檔中獲得什麼。最後，它爲你的寫做創建了一個時間表。

獲取相關的圖形/圖像

在肯定須要嵌入到文檔不一樣部分的各類虛擬輔助工具(信息圖、gif、視頻、tweet)時，有一個大綱很是有用。

若是你把這些相關的圖形放在手邊，會讓你的寫做過程變得更加輕鬆。

以正確的風格寫做

終於，你能夠開始寫做了！若是你已經完成了全部這些步驟，寫做應該會變得容易不少。但你仍然須要確保你的寫做風格適合技術文檔。

寫做須要通俗易懂、直接和專業，在技術文檔中不歡迎花哨或情緒化的文本。爲了幫助你保持這種風格，這裏有一些你應該培養的關鍵品質。

使用主動語態

在文章中使用主動語態是個好主意，由於它比被動語態更容易閱讀和理解。

主動語態是指句子的主語是主動執行動詞動做的人，被動語態是指主語是動詞動做的接受者。

這是一個被動語態的示例：每一個Web開發人員每一年應閱讀六次文檔。

下面是一個主動語態的例子：每一個web開發人員一年應該閱讀該文檔6次。

慎重選擇你的詞彙

詞語選擇很重要，確保你使用最適合上下文的詞彙。避免過分使用代詞，如「它」和「這」，由於讀者可能難以識別它們指的是哪一個名詞。

還要避免使用俚語和粗俗的語言——請記住，你是在爲更多的讀者寫做，他們的性格和文化傾向可能與你不一樣。

避免過多的行話

若是你是你所在領域的專家，很容易使用你熟悉的行話，而沒有意識到它可能會讓其餘讀者感到困惑。

你還應該避免使用之前沒有解釋過的首字母縮寫詞，這是一個例子：

不太清楚的是： PWAs真正被認爲是多平臺開發的將來。它們在Android和iOS上的可用性使其成爲將來的應用。

改進：漸進式網絡應用（PWA）是真正的多平臺開發的將來。它們在Android和iOS上的可用性使PWA成爲將來的應用。

使用簡單的語言

避免使用冗長的大詞，老是儘可能以最清晰的方式解釋概念和術語。

可視化格式化

一堆文字很難讀懂，即便是最清晰的指令也可能在視覺表現不佳的文檔中丟失。

他們說，一張圖片賽過千言萬語，即便在技術寫做中也是如此。

可是，並不是任何圖像均可以配上，僅用文本表達技術信息是困難的，放置恰當的圖像或圖表能夠澄清你的解釋。

人們也喜歡視覺效果，因此把它們插入到正確的位置是有幫助的。看看下面的圖片：

首先，這是一個沒有視覺效果的博客片斷：

這是同一博客的片斷，但帶有視覺效果：

在你的文章中添加圖片，可使內容更加貼切，更容易理解。除了圖片，你還能夠在必要時使用gif、表情、嵌入（社交媒體、代碼）和代碼片斷。

貼心的格式、模板和圖片或圖表也會讓你的文字對讀者更有幫助。

仔細檢查

任何類型的好文章都必須沒有拼寫和語法錯誤。這些錯誤可能看起來很明顯，但並不老是很容易發現它們（特別是在長篇文章中）。在點擊「發佈」以前，必定要仔細檢查你的拼寫。

有許多免費的工具，如Grammarly和Hemingway app，你能夠用來檢查語法和拼寫錯誤。你也能夠在發表前與別人分享你的文章草稿，讓他校對。

在哪裏發表文章

既然你已經決定開始從事技術寫做，這裏有一些不錯的平臺，你能夠在那裏免費發佈技術內容。他們還能夠幫助你創建一個吸引將來僱主的投資組合。

國內

Segmentfault 思否是中國領先的新一代開發者社區和專業的技術媒體，筆者主力發文平臺之一。

掘金 是一個幫助開發者成長的社區，特別是前端技術，如今已是整個行業裏最活躍的，筆者主力發文平臺之一。

CSDN 是全球知名中文IT技術交流平臺,建立於1999年，包含原創博客、精品問答、職業培訓、技術論壇、資源下載等產品服務，提供原創、優質、完整內容的專業IT技術開發社區。

知乎 有問題，上知乎。是中文互聯網知名的可信賴問答社區，致力於構建一我的人均可以便捷接入的知識分享網絡，讓人們便捷地與世界分享知識、經驗和看法，發現更大的世界。

國外

Dev.to是一個由數千名技術愛好者組成的社區，在這裏，做者和讀者均可以有意義地參與並分享想法和資源。

Hashnode是我經常使用的博客平臺，它有不少好處，好比自定義域名映射和互動社區。在這個平臺上設置博客也很簡單快速。

freeCodeCamp有一個很是大的社區和受衆，是一個發佈你的文章的好地方。可是，你須要使用一些之前的寫做示例來申請爲他們的出版物寫做。

你的申請可能被接受，也可能被拒絕，但不要灰心。你老是能夠在之後從新申請，由於你變得更好，誰知道呢？你可能會被錄取。

若是你真的爲他們寫文章，他們會在發佈前審覈和編輯你的文章，以確保你發佈的文章是最精緻的。他們還會將你的文章分享到他們的社交媒體平臺上，幫助更多的人閱讀。

Hackernoon擁有超過7,000名做家，能夠成爲一個很好的平臺，讓你開始向社區中天天超過20萬的讀者發佈你的文章。

Hacker Noon支持做者在平臺上發佈文章前對其進行校對，幫助他們避免常見錯誤。

技術寫做課程

就像其餘領域同樣，技術寫做也有各類流程、規則、最佳實踐等。

參加技術寫做的課程會幫助你完成你須要學習的每一件事，也能夠給你很大的信心，開啓你的寫做之旅。

你能夠查看如下一些技術寫做課程：

• Google技術寫做課程（免費）
• Udemy技術寫做課程（付費）
• Hashnode技術寫做訓練營（免費）

技術寫做論壇和社區

獨自一人，咱們能夠作得不多，但一塊兒，咱們能夠作得不少——海倫·凱勒。

成爲一個社區或論壇的一部分，與那些和你有一樣熱情的人一塊兒是有益的。你能夠獲得反饋、糾正、技巧，甚至從社區中的其餘做家那裏學習一些風格技巧。

如下是一些社區和論壇供你加入：

• Hashnode
• Dev.to
• Technical Writing World
• Technical Writer Forum
• Write the Docs Forum

下面是一些使人驚歎的技術做家

在個人技術寫做之旅中，我跟隨了一些偉大的技術做家，他們的寫做之旅、一致性和風格都激勵着我。

這些都是我仰望的做家，他們被我視爲技術寫做的虛擬導師。有時，他們會給我一些技術寫做技巧，我以爲頗有幫助，也從他們那裏學到了不少東西。

如下是其中一些做家（與他們的Twitter超連接）：

• Quincy Larson
• Edidiong Asikpo
• Catalin Pit
• Victoria Lo
• Bolaji Ayodeji
• Amruta Ranade
• Chris Bongers
• Colby Fayock

最後的話

你不須要技術寫做的學位就能夠開始發佈技術內容。你能夠開始在你的我的博客和公共GitHub知識庫上寫做，同時構建你的做品集並得到實踐經驗。

真的——開始寫吧。

經過爲現有程序或項目建立新的文檔來練習。GitHub上有不少開源項目，你能夠查看並添加到他們的文檔中。

有沒有一個你喜歡使用的應用程序，可是它的文檔寫得很糟糕？寫下你本身的，並在網上分享以得到反饋。你還能夠在hashnode上快速設置博客並開始寫做。

技術做家一直在學習。經過深刻到新的主題領域，並接受外部反饋，一個優秀的做家永遠不會中止磨練本身的技藝。

固然，優秀的做家也是貪婪的讀者。經過檢查大量閱讀和使用的文檔，你的寫做能力確定會獲得提升。

等不及要看你的技術文章了！

參考資料

Introduction to Technical Writing‌‌

How to structure a technical article‌‌

Understanding your audience, the why and how

‌‌Technical Writing template

我但願這能夠幫到你。