TranslateProject/published/202005/20200526 How to write about open source software.md

[#]: collector: (lujun9972)
[#]: translator: (wxy)
[#]: reviewer: (wxy)
[#]: publisher: (wxy)
[#]: url: (https://linux.cn/article-12267-1.html)
[#]: 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)

如何为开源软件写作文章
======

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

![](https://img.linux.net.cn/data/attachment/album/202005/31/115044ecfpxc2q9z0ca8wq.jpg)

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

### 你应该写什么？

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

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

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

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

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

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

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

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

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

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

### 你是为谁而写的？

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

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

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

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

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

### 言语很重要

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

#### 使用日常用语

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

使用 [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]
* [美联社文体手册][14]

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

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

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

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

本文由 [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/