[#]: collector: (lujun9972)
[#]: translator: (wxy)
[#]: reviewer: ( )
[#]: publisher: ( )
[#]: url: ( )
[#]: subject: (How to write about open source software)
[#]: via: (https://opensource.com/article/20/5/write-about-open-source-software)
[#]: author: (Dawn Parzych https://opensource.com/users/dawnparzych)

如何写好关于开源软件的文章
======

> 通过以下提示，成为一个更好的作家。

![Typewriter in the grass][1]

开始接触开源社区的一个方法就是写关于它的文章。你可以贡献技术文档，分享你如何使用软件，或者为我们写一篇文章。但是开始写作是说起来容易做起来难。我听到的最常见的两个不写文章的借口是：“我没有什么新东西可说”和“我不是一个好的作家”。我在这里是为了打破这两个误区。

### 你应该写什么？

> “寻找那些经常被遗漏的故事。”
> 埃里克·拉尔森

对于一些人来说，写作的最大障碍是产生一个想法或话题，以写出一个想法或话题。很容易就落入了这样的陷阱：“这个话题已经写过了，何必再麻烦。”

我不是第一个写文章的人，也不会是最后一个。我带来的是我独特的视角和这些年来所学到的东西。曾经有人向我请教过一些关于写作入门的建议，或者是如何让自己的写作更上一层楼。我决定把这些建议变成一篇文章。

文如其人，没有人会以你的方式来述事，你的经历和视角可能正是别人所需要的。

这里有一些提示，可以帮助你想出一个主题：

* 你最近学到了什么东西？写出你是如何学习的，你学到了什么，或者是什么事情让你感到惊讶。
* 你经常被问到的问题是什么？把答案写出来。
* 你最近是否在搜索一篇怎么做的文章，但在搜索结果中，你对排名靠前的文章不满意？请写出你要找的文章。
* 你是否参加过一次会议或研讨会？写一篇会后总结，说明你所学到的东西。
* 你开始使用新工具了吗？写一份操作指南或入门指南。

### 你写的是什么类型的文章？

有不同类型的文章，包括:

* 技术文档
* 操作指南
* 博客
* 白皮书或电子书
* 回顾性的文章

内容的类型会影响你的写作风格和语气。博客更多的是非正式和对话式的。技术文档更正式，更具有指导性。

### 你是为谁而写的？

每一篇文章都应该有一个受众。受众是指你所写的对象是什么类型的人。在你开始写作之前，写下你的读者的一些特征，这对你的读者有帮助。重要的是要考虑到你要为谁写，以及你**不是为**谁写的 —— 确定你的目标受众将决定你的目标受众，要包括哪些内容和不包括哪些内容。

例如，我在写这篇文章的时候，我设想的目标受众是这样的。

* 有基本的写作和语法知识
* 有兴趣提高写作能力
* 在技术领域担任开发人员、销售工程师、客户经理或类似职位的工作
* 不是有经验或高级作家，可能在个人或工作博客上发表过几篇文章，想写更多的文章。
* 非虚构写作

如果你有针对多个受众的内容，可以考虑针对不同的受众将其分解成不同的内容。在你的受众中需要考虑的一些部分。

* 专业水平：新手、中级、高级
* 作用：管理人员、个人贡献者
* 目标：他们为什么要阅读这些？

### 言语很重要

你选择的词语会对读者产生影响。晦涩难懂的词会使文章更难理解，不常见的词会让读者觉得自己很笨，某些词可能会不小心冒犯读者。作为一个作家，你的目标是避免所有这些。下面是怎么做的。

#### 使用日常用语

不要把写作作为炫耀你的词汇量或你从“每日一字”台历上学到的单词的方式。写作是为了让读者能够理解。每一篇文章都有一个关联的阅读水平。如果你写的是技术文档，那么你的目标大约是初中的阅读水平。这并不意味着你的受众只有初中的教育水平。它意味着你的写作会更容易被人理解。你想让人们对这些言语过目不忘，还是想让他们觉得自己学到了什么？虽然你可以使用长而复杂的词汇，但并不意味着你应该这样做。使用简单的语言不一定意味着你的文章会很无聊。

使用 [Hemingway 应用][2]等工具来检查你的作文的可读性（它不是开源的，但很优秀）。比如说，这篇文章经过初稿后，被评定为五级阅读水平。Hemingway 还提供了如何改进写作的建议 —— 找出难读的句子或需要改变选词的地方。

如果你正在纠结于想出替代词，可以查看 [Plain English Campaign][3] 的建议或 [Power Thesaurus][4] 的众包建议。

#### 知道应该规避哪些词

> “每次你想写‘非常’的时候，就用‘该死的’代替；你的编辑会把它删掉，写出来的东西就会像它应该写的那样。”
> 马克·吐温

在写教程或指南的时候，这里有一些要避免的词，包括“<ruby>简单<rt>simple</rt></ruby>”、“<ruby>容易<rt>easy</rt></ruby>”和“<ruby>就这样<rt>just</rt></ruby>”。你是你所写的主题的专家，经过多年的实践，可能会觉得事情很简单。而初学者可能会觉得事情不简单，也不容易。你的读者可能会感到沮丧，因为他们觉得过程或解释并不简单。

你是否曾经因为无法理解作者的意思而不得不多次重读一个句子或段落？你有没有因为一篇文章对你来说没有意义而放弃过？我有过。

作为一个作家，你希望你的读者感到困惑或不理解吗？我希望不会。

在你的写作中要避免的其他词语

* <ruby>这件事<rt>That</rt></ruby>
* <ruby>真的<rt>Really</rt></ruby>
* <ruby>非常<rt>Very</rt></ruby>
* <ruby>所以<rt>So</rt></ruby>
* <ruby>为了<rt>In order to</rt></ruby>

一般来说，这些词可以在不改变句子意思的情况下删除。

在我写完之后，我会在一个文档中搜索这些词的实例。当我在这个文档中搜索时，我发现了以下这句话。

> “这并不意味着你的受众只有初中的教育水平*这件事*，而意味着你的写作会更容易被理解*这件事*。”

这句话中出现了两个“<ruby>这件事<rt>That</rt></ruby>”的例子。它们并没有给句子增加价值。它们可以被删除而不改变其意义。删除这些实例可以缩短句子，而更短的句子更容易理解。而说到短句，我还把它改写成了两句话。

> “这并不意味着你的受众只有初中的教育水平。它意味着你的写作会更容易被人理解。”

#### 使用包容性语言

词语和短语的历史背景会让人感到被排斥或反感。在写作时，你要让读者感到被包容。当你使用包容性的语言时，会让读者感到被理解、被尊重，感觉自己是属于他们的。我参考了 Buffer 中的这篇[关于使用包容性语言的指南][5]。

### 修订和编辑

> “几乎所有好的写作都是从可怕的第一次努力开始的。你需要从某个地方开始。”
> 安妮·拉莫特

写作是一个迭代的过程。如果你认为作家们坐在办公桌前，在一个小时内就能完成一篇文章发表，那么请你再想一想。有些文章需要我花几个星期的时间来完成。以下是我的一个标准流程：

* 写一个粗略的初稿。我说的粗略，我的意思是*草稿*。我写的时候不用担心语法问题。我的想法是让文字从我的脑海中浮现出来，写在纸上。这一步可能需要一个小时到几周的时间。
* 将草稿放一段时间。这可能需要几个小时到几天的时间，这取决于出版时间线。
* 审阅草稿。进行调整和编辑。
* 征求反馈意见，可以是同事或朋友的反馈意见。在这个阶段的反馈中，我的重点是明确性。是否有意义？是否有什么令人困惑的地方，有什么缺失的部分？
* 纳入反馈意见。无论你的写作经验有多丰富，其他作者审阅你的作品，都会让你的作品变得更好。

在这个阶段，我有了一个相当扎实的草稿。现在到了我最不喜欢的写作部分 —— 编辑。我之前提到的 Hemingway 应用不仅能告诉你阅读水平，还能提供改进写作的建议。我还使用 Grammarly 来帮助编辑语法。关于 Grammarly 的开源替代工具，请查看[语言工具][6]或这篇文章中的[开源写作工具][7]。

我的写作挑战之一就是适当地使用逗号。Grammarly 可以帮助我找出我错过或误用逗号的地方。Grammarly 发现了 43 个与这篇文章的最终草稿的正确性有关的问题。其中大部分是逗号错误。

![Errors identified by Grammarly][8]

除了语法错误之外，该应用程序还提供了一些建议，以帮助提高清晰度、参与度和表达能力（其中一些功能可能在免费版中没有）。这包括单词选择和使用主动语气与被动语气等。有些建议我接受，有些则拒绝。在审查了所有的警报和建议后，Grammarly 会在所有的维度上进行反馈。

![Grammarly results][10]

不要害怕寻求写作上的帮助。每一个好的作家背后都有一个好的编辑或好的编辑应用。

### 风格指南

文体指南为改进写作中的交流提供了标准。它们包括标点符号、语法和用词等方面。如果是为你的公司撰写文档，请检查一下是否使用了文体指南。如果没有文体指南，或者你是为自己写的，下面是一些常用的文体指南。

* [芝加哥文体手册][11]
* [谷歌开发者文档指南][12]
* [微软写作风格指南][13]
* [AP 风格手册] [14]

写作是一种与社会分享自己的思想和知识的方式。开始写作的唯一方法就是开始打字。用这些建议来微调你的写作。

--------------------------------------------------------------------------------

via: https://opensource.com/article/20/5/write-about-open-source-software

作者：[Dawn Parzych][a]
选题：[lujun9972][b]
译者：[wxy](https://github.com/wxy)
校对：[校对者ID](https://github.com/校对者ID)

本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出

[a]: https://opensource.com/users/dawnparzych
[b]: https://github.com/lujun9972
[1]: https://opensource.com/sites/default/files/styles/image-full-size/public/lead-images/doc-dish-lead.png?itok=h3fCkVmU (Typewriter in the grass)
[2]: http://www.hemingwayapp.com/
[3]: http://www.plainenglish.co.uk/the-a-z-of-alternative-words.html
[4]: https://www.powerthesaurus.org/
[5]: https://open.buffer.com/inclusive-language-tech/
[6]: https://languagetool.org/
[7]: https://opensource.com/article/20/3/open-source-writing-tools
[8]: https://opensource.com/sites/default/files/uploads/grammarlyerrors.png (Errors identified by Grammarly)
[9]: https://creativecommons.org/licenses/by-sa/4.0/
[10]: https://opensource.com/sites/default/files/uploads/grammarlyresults.png (Grammarly results)
[11]: https://www.chicagomanualofstyle.org/home.html
[12]: https://developers.google.com/style
[13]: https://docs.microsoft.com/en-us/style-guide/welcome/
[14]: https://www.apstylebook.com/