[[354651]]

如果你喜歡寫作和技術(shù)，技術(shù)寫作可能是一個(gè)適合你的職業(yè)。如果你喜歡技術(shù)，但又不是真的整天喜歡編碼，也可以做一些別的事情。

如果你喜歡通過教導(dǎo)他人來學(xué)習(xí)，為開源項(xiàng)目做出貢獻(xiàn)，并教導(dǎo)他人如何做到這一點(diǎn)，或者基本上喜歡通過你的寫作以簡(jiǎn)單的方式解釋復(fù)雜的概念，技術(shù)寫作也可能適合你。

讓我們深入了解基礎(chǔ)知識(shí)，了解你在開始技術(shù)寫作時(shí)應(yīng)該知道和考慮的問題。

目錄

• 什么是技術(shù)寫作?
• 技術(shù)寫作的好處
• 作為技術(shù)作家必須具備的技能
  • 了解正確的英語(yǔ)用法
  • 知道如何清楚、簡(jiǎn)單地解釋事物
  • 具備一定的寫作技巧 ??
• 技術(shù)寫作過程
  • 分析并了解你的讀者是誰(shuí)
  • 考慮用戶體驗(yàn)
  • 計(jì)劃你的文檔
  • 對(duì)該主題進(jìn)行深入研究
  • 做一個(gè)大綱
  • 獲取相關(guān)的圖形/圖像
  • 以正確的風(fēng)格寫作
• 在哪里發(fā)表文章
  • 國(guó)內(nèi)
  • 國(guó)外
• 技術(shù)寫作課程
• 技術(shù)寫作論壇和社區(qū)
• 下面是一些令人驚嘆的技術(shù)作家
• 最后的話
• 參考資料

什么是技術(shù)寫作?

技術(shù)寫作是一門藝術(shù)，提供細(xì)節(jié)導(dǎo)向的指導(dǎo)，以幫助用戶理解特定的技能或產(chǎn)品。

技術(shù)作者是寫這些說明的人，也稱為技術(shù)文檔或教程。這可能包括用戶手冊(cè)、在線支持文章或者程序員/API 開發(fā)者的內(nèi)部文檔。

技術(shù)寫作者的交流方式是將技術(shù)信息呈現(xiàn)給讀者，使讀者能夠?qū)⑦@些信息用于預(yù)期的目的。

技術(shù)寫作的好處

技術(shù)寫作者也是是終身學(xué)習(xí)者。由于這份工作需要用簡(jiǎn)單而直接的術(shù)語(yǔ)來表達(dá)復(fù)雜的概念，所以你必須精通你所寫的領(lǐng)域，或者愿意學(xué)習(xí)它。

這很好，因?yàn)槊垦芯亢途帉懸环菪碌募夹g(shù)文檔，你就會(huì)成為該領(lǐng)域的專家。

技術(shù)寫作還能讓你更好地理解用戶的感受，它幫助你更多地關(guān)注讀者或用戶對(duì)產(chǎn)品的感受，而不是你的想法。

你也可以通過為組織撰稿來賺錢。下面是一些付錢給你為他們寫文章的機(jī)構(gòu)，比如Smashing 雜志、AuthO、Twilio和Stack Overflow。

除此以外，你還可以為開源社區(qū)做貢獻(xiàn)，參與 Google Season of Docs 和 Outreachy 等付費(fèi)開源項(xiàng)目。

你也可以把技術(shù)寫作作為一個(gè)全職職業(yè)——很多公司都需要有這些技能的人。

作為技術(shù)作家必須具備的技能

了解正確的英語(yǔ)用法

在你考慮寫作之前，有必要掌握好英語(yǔ)、時(shí)態(tài)、拼寫和基本語(yǔ)法。你的讀者不希望讀到一篇充滿錯(cuò)誤語(yǔ)法和糟糕詞匯選擇的文章。

知道如何清楚、簡(jiǎn)單地解釋事物

知道如何實(shí)現(xiàn)功能并不一定意味著你可以與其他人清楚地交流該過程。

為了成為一名優(yōu)秀的老師，你必須具有同理心，能夠以適合你的目標(biāo)受眾的方式教授或描述術(shù)語(yǔ)。

如果你不能向六歲的孩子解釋它，那么你自己也不了解。——艾爾伯特·愛因斯坦

具備一定的寫作技巧 ??

我相信，作家是天生的，而不是后天的，而你只有通過實(shí)際寫作才能學(xué)會(huì)如何寫作。

你可能永遠(yuǎn)都不知道你有寫作的能力，直到你把筆放到紙上。而要想知道自己是否有一定的寫作能力，只有一個(gè)辦法，那就是通過寫作。

所以我鼓勵(lì)你從今天開始寫作。你可以選擇從我在本節(jié)中列出的任何一個(gè)平臺(tái)開始，以擴(kuò)展你的寫作能力。

當(dāng)然，擁有一些技術(shù)領(lǐng)域的經(jīng)驗(yàn)也是巨大的好處。

技術(shù)寫作過程

分析并了解你的讀者是誰(shuí)

當(dāng)你在寫一篇技術(shù)文章時(shí)，要考慮的最大因素是你的預(yù)期/期望受眾。它應(yīng)該始終在你的腦海中占據(jù)最重要的位置。

一個(gè)好的技術(shù)寫作者會(huì)根據(jù)讀者的語(yǔ)境來寫作。舉個(gè)例子，比如說你要寫一篇針對(duì)初學(xué)者的文章。重要的是，不要假設(shè)他們已經(jīng)知道某些概念。

你可以在文章開頭概述任何必要的先決條件。這將確保你的讀者在直接進(jìn)入你的文章之前已經(jīng)(或能夠獲得)他們所需要的知識(shí)。

你還可以加入有用資源的鏈接，這樣你的讀者只需點(diǎn)擊一下就能獲得他們需要的信息。

為了知道你是為誰(shuí)而寫，你必須盡可能多地收集關(guān)于誰(shuí)將使用該文件的信息。

重要的是要知道你的讀者是否在該領(lǐng)域有專業(yè)知識(shí)，是否這個(gè)話題對(duì)他們來說是全新的，或者他們是否介于兩者之間。

你的讀者也會(huì)有他們自己的期望和需求。當(dāng)讀者開始閱讀文檔時(shí)，你必須確定他們?cè)趯ふ沂裁矗约八麄儗闹蝎@得什么。

要了解你的讀者，請(qǐng)?jiān)陂_始寫作之前先問自己以下幾個(gè)問題：

• 我的讀者是誰(shuí)?
• 他們需要什么?
• 他們將在哪里閱讀?
• 他們什么時(shí)候閱讀?
• 他們?yōu)槭裁匆喿x?
• 他們將如何閱讀?

這些問題還能幫助你思考讀者在閱讀你的寫作時(shí)的體驗(yàn)，這一點(diǎn)我們現(xiàn)在要多說幾句。

考慮用戶體驗(yàn)

用戶體驗(yàn)在技術(shù)文檔中和在網(wǎng)絡(luò)上的任何地方一樣重要。

既然你知道了你的受眾和他們的需求，就要記住文檔本身是如何為他們的需求服務(wù)的。很容易忽略讀者實(shí)際會(huì)如何使用文檔。

寫作時(shí)，不斷后退一步，把自己當(dāng)成讀者來看待文檔。問問自己：它是可訪問的嗎?你的讀者將如何使用它?他們何時(shí)會(huì)使用它?是否易于閱讀?

目的是編寫一個(gè)對(duì)讀者有用和可用的文檔。

計(jì)劃你的文檔

記住你的用戶是誰(shuí)，然后你就可以對(duì)你的文檔進(jìn)行構(gòu)思和規(guī)劃。

這個(gè)過程包括許多步驟，我們現(xiàn)在將繼續(xù)進(jìn)行。

對(duì)該主題進(jìn)行深入研究

在規(guī)劃你的文檔時(shí)，你必須研究你要寫的主題。有大量的資源只需在谷歌上搜索一下就可以供你消費(fèi)，并從中獲得更深的見解。

不要試圖從別人的作品或文章中摘錄下來，然后當(dāng)作自己的作品，因?yàn)檫@就是抄襲。相反，將這些資源作為你工作的參考和想法。

盡可能多地使用谷歌，從研究期刊、書籍或新聞中獲取事實(shí)和數(shù)據(jù)，盡可能多地收集有關(guān)你的主題的信息。然后你就可以開始做一個(gè)大綱了。

做一個(gè)大綱

在擴(kuò)展文檔內(nèi)容之前先列出提綱，這有助于你更專注地寫作。它還可以讓你組織你的思路，實(shí)現(xiàn)你的寫作目標(biāo)。

提綱還可以幫助你確定你希望讀者從文檔中得到什么。最后，它為你的寫作建立了一個(gè)時(shí)間表。

獲取相關(guān)的圖形/圖像

在確定需要嵌入到文檔不同部分的各種虛擬輔助工具(信息圖、gif、視頻、tweet)時(shí)，有一個(gè)大綱非常有用。

如果你把這些相關(guān)的圖形放在手邊，會(huì)讓你的寫作過程變得更加輕松。

以正確的風(fēng)格寫作

終于，你可以開始寫作了!如果你已經(jīng)完成了所有這些步驟，寫作應(yīng)該會(huì)變得容易很多。但你仍然需要確保你的寫作風(fēng)格適合技術(shù)文檔。

寫作需要通俗易懂、直接和專業(yè)，在技術(shù)文檔中不歡迎花哨或情緒化的文本。為了幫助你保持這種風(fēng)格，這里有一些你應(yīng)該培養(yǎng)的關(guān)鍵品質(zhì)。

使用主動(dòng)語(yǔ)態(tài)

在文章中使用主動(dòng)語(yǔ)態(tài)是個(gè)好主意，因?yàn)樗缺粍?dòng)語(yǔ)態(tài)更容易閱讀和理解。

主動(dòng)語(yǔ)態(tài)是指句子的主語(yǔ)是主動(dòng)執(zhí)行動(dòng)詞動(dòng)作的人，被動(dòng)語(yǔ)態(tài)是指主語(yǔ)是動(dòng)詞動(dòng)作的接受者。

這是一個(gè)被動(dòng)語(yǔ)態(tài)的示例：每個(gè) Web 開發(fā)人員每年應(yīng)閱讀六次文檔。

下面是一個(gè)主動(dòng)語(yǔ)態(tài)的例子：每個(gè) web 開發(fā)人員一年應(yīng)該閱讀該文檔 6 次。

慎重選擇你的詞匯

詞語(yǔ)選擇很重要，確保你使用最適合上下文的詞匯。避免過度使用代詞，如“它”和“這”，因?yàn)樽x者可能難以識(shí)別它們指的是哪個(gè)名詞。

還要避免使用俚語(yǔ)和粗俗的語(yǔ)言——請(qǐng)記住，你是在為更多的讀者寫作，他們的性格和文化傾向可能與你不同。

避免過多的行話

如果你是你所在領(lǐng)域的專家，很容易使用你熟悉的行話，而沒有意識(shí)到它可能會(huì)讓其他讀者感到困惑。

你還應(yīng)該避免使用以前沒有解釋過的首字母縮寫詞，這是一個(gè)例子：

不太清楚的是：PWAs真正被認(rèn)為是多平臺(tái)開發(fā)的未來。它們?cè)?Android 和 iOS 上的可用性使其成為未來的應(yīng)用。

改進(jìn)：漸進(jìn)式網(wǎng)絡(luò)應(yīng)用(PWA)是真正的多平臺(tái)開發(fā)的未來。它們?cè)?Android 和 iOS 上的可用性使 PWA 成為未來的應(yīng)用。

使用簡(jiǎn)單的語(yǔ)言

避免使用冗長(zhǎng)的大詞，總是盡量以最清晰的方式解釋概念和術(shù)語(yǔ)。

可視化格式化

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

他們說，一張圖片勝過千言萬(wàn)語(yǔ)，即使在技術(shù)寫作中也是如此。

但是，并非任何圖像都可以配上，僅用文本表達(dá)技術(shù)信息是困難的，放置恰當(dāng)?shù)膱D像或圖表可以澄清你的解釋。

人們也喜歡視覺效果，所以把它們插入到正確的位置是有幫助的?？纯聪旅娴膱D片：

首先，這是一個(gè)沒有視覺效果的博客片段：

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

在你的文章中添加圖片，可以使內(nèi)容更加貼切，更容易理解。除了圖片，你還可以在必要時(shí)使用 gif、表情、嵌入(社交媒體、代碼)和代碼片段。

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

仔細(xì)檢查

任何類型的好文章都必須沒有拼寫和語(yǔ)法錯(cuò)誤。這些錯(cuò)誤可能看起來很明顯，但并不總是很容易發(fā)現(xiàn)它們(特別是在長(zhǎng)篇文章中)。在點(diǎn)擊“發(fā)布”之前，一定要仔細(xì)檢查你的拼寫。

有許多免費(fèi)的工具，如Grammarly和Hemingway app，你可以用來檢查語(yǔ)法和拼寫錯(cuò)誤。你也可以在發(fā)表前與別人分享你的文章草稿，讓他校對(duì)。

在哪里發(fā)表文章

既然你已經(jīng)決定開始從事技術(shù)寫作，這里有一些不錯(cuò)的平臺(tái)，你可以在那里免費(fèi)發(fā)布技術(shù)內(nèi)容。他們還可以幫助你建立一個(gè)吸引未來雇主的投資組合。

國(guó)內(nèi)

Segmentfault 思否是中國(guó)領(lǐng)先的新一代開發(fā)者社區(qū)和專業(yè)的技術(shù)媒體，筆者主力發(fā)文平臺(tái)之一。

掘金 是一個(gè)幫助開發(fā)者成長(zhǎng)的社區(qū)，特別是前端技術(shù)，現(xiàn)在已經(jīng)是整個(gè)行業(yè)里最活躍的，筆者主力發(fā)文平臺(tái)之一。

CSDN 是全球知名中文 IT 技術(shù)交流平臺(tái),創(chuàng)建于 1999 年，包含原創(chuàng)博客、精品問答、職業(yè)培訓(xùn)、技術(shù)論壇、資源下載等產(chǎn)品服務(wù)，提供原創(chuàng)、優(yōu)質(zhì)、完整內(nèi)容的專業(yè) IT 技術(shù)開發(fā)社區(qū)。

知乎 有問題，上知乎。是中文互聯(lián)網(wǎng)知名的可信賴問答社區(qū)，致力于構(gòu)建一個(gè)人人都可以便捷接入的知識(shí)分享網(wǎng)絡(luò)，讓人們便捷地與世界分享知識(shí)、經(jīng)驗(yàn)和見解，發(fā)現(xiàn)更大的世界。

國(guó)外

Dev.to是一個(gè)由數(shù)千名技術(shù)愛好者組成的社區(qū)，在這里，作者和讀者都可以有意義地參與并分享想法和資源。

Hashnode是我常用的博客平臺(tái)，它有很多好處，比如自定義域名映射和互動(dòng)社區(qū)。在這個(gè)平臺(tái)上設(shè)置博客也很簡(jiǎn)單快速。

freeCodeCamp 有一個(gè)非常大的社區(qū)和受眾，是一個(gè)發(fā)布你的文章的好地方。但是，你需要使用一些以前的寫作示例來申請(qǐng)為他們的出版物寫作。

你的申請(qǐng)可能被接受，也可能被拒絕，但不要灰心。你總是可以在以后重新申請(qǐng)，因?yàn)槟阕兊酶?，誰(shuí)知道呢?你可能會(huì)被錄取。

如果你真的為他們寫文章，他們會(huì)在發(fā)布前審核和編輯你的文章，以確保你發(fā)布的文章是最精致的。他們還會(huì)將你的文章分享到他們的社交媒體平臺(tái)上，幫助更多的人閱讀。

Hackernoon 擁有超過 7,000 名作家，可以成為一個(gè)很好的平臺(tái)，讓你開始向社區(qū)中每天超過 20 萬(wàn)的讀者發(fā)布你的文章。

Hacker Noon 支持作者在平臺(tái)上發(fā)布文章前對(duì)其進(jìn)行校對(duì)，幫助他們避免常見錯(cuò)誤。

技術(shù)寫作課程

就像其他領(lǐng)域一樣，技術(shù)寫作也有各種流程、規(guī)則、最佳實(shí)踐等。

參加技術(shù)寫作的課程會(huì)幫助你完成你需要學(xué)習(xí)的每一件事，也可以給你很大的信心，開啟你的寫作之旅。

你可以查看以下一些技術(shù)寫作課程：

• Google 技術(shù)寫作課程(免費(fèi))
• Udemy 技術(shù)寫作課程(付費(fèi))
• Hashnode 技術(shù)寫作訓(xùn)練營(yíng)(免費(fèi))

技術(shù)寫作論壇和社區(qū)

獨(dú)自一人，我們可以做得很少，但一起，我們可以做得很多——海倫·凱勒。

成為一個(gè)社區(qū)或論壇的一部分，與那些和你有同樣熱情的人一起是有益的。你可以得到反饋、糾正、技巧，甚至從社區(qū)中的其他作家那里學(xué)習(xí)一些風(fēng)格技巧。

以下是一些社區(qū)和論壇供你加入：

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

下面是一些令人驚嘆的技術(shù)作家

在我的技術(shù)寫作之旅中，我跟隨了一些偉大的技術(shù)作家，他們的寫作之旅、一致性和風(fēng)格都激勵(lì)著我。

這些都是我仰望的作家，他們被我視為技術(shù)寫作的虛擬導(dǎo)師。有時(shí)，他們會(huì)給我一些技術(shù)寫作技巧，我覺得很有幫助，也從他們那里學(xué)到了很多東西。

以下是其中一些作家(與他們的 Twitter 超鏈接)：

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

最后的話

你不需要技術(shù)寫作的學(xué)位就可以開始發(fā)布技術(shù)內(nèi)容。你可以開始在你的個(gè)人博客和公共 GitHub 知識(shí)庫(kù)上寫作，同時(shí)構(gòu)建你的作品集并獲得實(shí)踐經(jīng)驗(yàn)。

真的——開始寫吧。

通過為現(xiàn)有程序或項(xiàng)目創(chuàng)建新的文檔來練習(xí)。GitHub 上有很多開源項(xiàng)目，你可以查看并添加到他們的文檔中。

有沒有一個(gè)你喜歡使用的應(yīng)用程序，但是它的文檔寫得很糟糕?寫下你自己的，并在網(wǎng)上分享以獲得反饋。你還可以在 hashnode 上快速設(shè)置博客并開始寫作。

技術(shù)作家一直在學(xué)習(xí)。通過深入到新的主題領(lǐng)域，并接受外部反饋，一個(gè)優(yōu)秀的作家永遠(yuǎn)不會(huì)停止磨練自己的技藝。

當(dāng)然，優(yōu)秀的作家也是貪婪的讀者。通過檢查大量閱讀和使用的文檔，你的寫作能力肯定會(huì)得到提高。

等不及要看你的技術(shù)文章了!

參考資料

Introduction to Technical Writing??

How to structure a technical article??

Understanding your audience, the why and how

??Technical Writing template

我希望這可以幫到你。

查看本文鏈接請(qǐng)點(diǎn)擊文末左下角閱讀原文鏈接

原文：https://www.freecodecamp.org/news/technical-writing-for-beginners/

作者：Amarachi Emmanuela Azubuike

本文轉(zhuǎn)載自微信公眾號(hào)「前端全棧開發(fā)者  」，可以通過以下二維碼關(guān)注。轉(zhuǎn)載本文請(qǐng)聯(lián)系前端全棧開發(fā)者公眾號(hào)。