如何為開源軟體寫作文章
開始接觸開源社區的一個方法就是寫關於它的文章。你可以貢獻技術文檔,分享你如何使用軟體,或者為我們社區寫一篇文章。但是開始寫作說起來容易做起來難。我聽到的最常見的兩個不寫文章的借口是:「我沒有什麼新東西可寫」和「我不是一個好的作者」。我在這裡是為了打破這兩個誤區。
你應該寫什麼?
「尋找那些經常被遺漏的故事。」 埃里克·拉爾森
對於某些人來說,寫作的最大障礙是找到要寫的想法或話題。很容易就落入了這樣的思維陷阱:「這個話題已經寫過了,何必再麻煩。」
我不是第一個寫文章的人,也不會是最後一個。我帶來的是我獨特的視角和這些年來所學到的東西。曾經有人向我請教過一些關於寫作入門的建議,或者是如何讓自己的寫作更上一層樓。我決定把這些建議變成一篇文章。
文如其人,沒有人會以你的方式來述事,你的經驗和觀點可能正是別人所需要的。
這裡有一些提示,可以幫助你想出一個主題:
- 你最近學到了什麼東西?寫出你是如何學習的,你學到了什麼,或使你感到驚訝的事情。
- 你經常被問到的問題是什麼?把答案寫出來。
- 你最近是否在搜索一篇怎麼做的文章,但在搜索結果中,你對排名靠前的文章不滿意?請寫出你要找的文章。
- 你是否參加過會議或研討會?寫一篇會後總結來說明你所學到的東西。
- 你開始使用新工具了嗎?寫一份操作指南或入門指南。
你寫的是什麼類型的文章?
有不同類型的文章,包括:
- 技術文檔
- 操作指南
- 博客
- 白皮書或電子書
- 回顧性的文章
內容的類型會影響你的寫作風格和語氣。博客更加非正式和是對話式的。而技術文檔更正式,更具有指導性。
你是為誰而寫的?
每一篇文章都應該有一個單一的受眾。受眾是指你為之寫作的對象是什麼類型的人。在你開始寫作之前,寫下你的讀者的一些特徵是有助於寫作的。重要的是要考慮到你要為誰寫,以及你不是為誰寫的 —— 確定你的目標受眾將決定要包括哪些內容和不包括哪些內容。
例如,我在寫這篇文章的時候,我設想的目標受眾是這樣的:
- 有基本的寫作和語法知識
- 有興趣提高寫作能力
- 在技術領域擔任開發人員、銷售工程師、客戶經理或類似職位的工作
- 不是經驗豐富或資深的作者,可能在個人或工作博客上發表過幾篇文章,想寫更多的文章。
- 非虛構寫作
如果你有針對多個受眾的內容,可以考慮針對不同的受眾將其分解成不同的內容。對你的受眾要考慮的一些方面:
- 專業水平:新手、中級、高級
- 作用:管理人員、個人貢獻者
- 目標:他們為什麼要閱讀這些?
言語很重要
你選擇的言語會對讀者產生影響。晦澀難懂的辭彙會使文章更難理解,不常見的辭彙會讓讀者覺得自己很笨,某些辭彙可能會不小心冒犯讀者。作為一個作者,你的目標是避免所有這些。下面是怎麼做的:
使用日常用語
不要把寫作作為炫耀你的辭彙量或你從「每日一字」枱曆上學到的單詞的方式。寫作是為了讓讀者能夠理解。每一篇文章都有相關的閱讀水平。如果你寫的是技術文檔,那麼你的目標大約是初中的閱讀水平。這並不意味著你的受眾只有初中的教育水平。它意味著你的寫作會更容易被人理解。你想讓人們對這些言語過目不忘,還是想讓他們覺得自己學到了什麼?雖然你可以使用長而複雜的辭彙,但並不意味著你應該這樣做。使用簡單的語言不一定意味著你的文章會很無聊。
使用 Hemingway 應用等工具來檢查你的作品的可讀性(它不是開源的,但很優秀)。比如說,在初稿之後,這篇文章被評定為五年級的閱讀水平。Hemingway 還提供了如何改進寫作的建議 —— 找出難以理解的句子或需要改變選詞的地方。
如果你想要找出替代的辭彙,可以查看 Plain English Campaign 的建議或 Power Thesaurus 的眾包建議。
知道應該規避哪些詞
「每次你想寫『非常』的時候,就用『該死的』代替;你的編輯會把它刪掉,而作品就會如它應有的那樣。」 馬克·吐溫
在寫教程或指南的時候,這裡有一些要避免的詞,包括「 簡單 」、「 容易 」和「 就這樣 」。你是你所寫的主題的專家,經過多年的實踐,可能會覺得事情很簡單。而初學者可能會覺得事情不「簡單」,也不「容易」。你的讀者可能會感到沮喪,因為他們覺得過程或解釋並不簡單。
你是否曾經因為無法理解作者的意思而不得不反覆重讀一個句子或段落?你有沒有因為一篇文章對你來說沒有意義而放棄過?我有過。
作為一個作者,你希望你的讀者感到困惑或不理解嗎?我希望不會。
在你的寫作中要避免的其它詞語:
- 這件事
- 真的
- 非常
- 所以
- 為了
一般來說,這些詞可以在不改變句子意思的情況下刪除。
在我寫完之後,我會在文檔中搜索這些詞。當我在這篇文章中搜索時,我發現了以下這句話:
「這並不意味著你的受眾只有初中的教育水平這件事,而意味著你的寫作會更容易被理解這件事。」
這句話中出現了兩個「 這件事 」的例子。它們並沒有給句子增加價值。它們可以被刪除而不改變其含義。刪除這些辭彙可以縮短句子,並且更短的句子更容易理解。而說到短句,我還把它改寫成了兩句話。
「這並不意味著你的受眾只有初中的教育水平。它意味著你的寫作會更容易被人理解。」
使用包容性語言
詞語和短語的歷史背景可能會導致人們感到被排斥或冒犯。在寫作時,你要讓讀者感到被包容。當你使用包容性的語言時,會讓讀者感到被理解、被尊重,感覺被包容。我參考了 Buffer 中的這篇關於使用包容性語言的指南。
修訂和編輯
「幾乎所有好的寫作都是從糟糕的第一次努力開始的。你需要從某個地方開始。」 安妮·拉莫特
寫作是一個迭代的過程。如果你認為作者們坐在辦公桌前,在一個小時內就能完成一篇文章準備發表,那麼請你再想一想。有些文章需要我花幾個星期的時間來完成。以下是我的標準流程:
- 寫一個粗略的初稿。我說的粗略,我的意思是粗陋。寫的時候不用擔心語法問題。目的是讓文字從我的腦海中浮現出來,寫在紙上。這一步可能需要一個小時到幾周的時間。
- 將草稿放一段時間。這可能需要幾個小時到幾天的時間,這取決於出版時間線。
- 審閱草稿。進行調整和編輯。
- 徵求反饋意見,可以是同事或朋友的反饋意見。在這個階段的反饋中,我的重點是明確性。是否有意義?是否有什麼令人困惑的地方?有什麼缺失的部分?
- 納入反饋意見。無論你的寫作經驗有多豐富,讓其他作者審閱你的作品,都會讓你的作品變得更好。
在這個階段,我有了一個相當紮實的草稿。現在到了我最不喜歡的寫作部分 —— 編輯。我之前提到的 Hemingway 應用不僅能告訴你閱讀水平,還能提供改進寫作的建議。我還使用 Grammarly 來幫助編輯語法。關於 Grammarly 的開源替代工具,請查看語言工具網站或這篇文章中的開源寫作工具。
我的寫作挑戰之一就是適當地使用逗號。Grammarly 可以幫助我找出我缺失或濫用逗號的地方。Grammarly 發現了 43 個這篇文章的最終草稿的正確性問題。其中大部分是逗號錯誤。
![Errors identified by Grammarly](/data/attachment/album/202005/31/115127aiyzt6ma2c2r8grr.png "Errors identified by Grammarly")
除了語法錯誤之外,該應用程序還提供了一些建議,以幫助提高清晰度、參與度和表達能力(其中一些功能可能在免費版中沒有)。這包括單詞選擇和使用主動語氣與被動語氣等。有些建議我接受,有些則拒絕。在審查了所有的警報和建議後,Grammarly 會在各個方面進行反饋。
![Grammarly results](/data/attachment/album/202005/31/115128vppm5mt7xmmzgpjz.png "Grammarly results")
不要害怕尋求寫作上的幫助。每一個好的作者背後都有一個好的編輯或好的編輯應用。
文體指南
文體指南為改善書面交流提供了標準。它們包括標點符號、語法和用詞等方面。如果是為你的公司撰寫文檔,請檢查一下公司是否有文體指南。如果沒有文體指南,或者你是為自己寫的,下面是一些常用的文體指南:
寫作是一種與社區分享自己的思想和知識的方式。開始寫作的唯一方法就是開始打字。用這些建議來微調你的寫作。
via: https://opensource.com/article/20/5/write-about-open-source-software
作者:Dawn Parzych 選題:lujun9972 譯者:wxy 校對:wxy
本文轉載來自 Linux 中國: https://github.com/Linux-CN/archive