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

图片来源：

原始照片由 jetheriot 拍摄。由 Rikki Endsley 修改。CC BY-SA 2.0 许可。

参与开源社区的一种方式是撰写关于它的文章。您可以为技术文档做出贡献，分享您如何使用该软件，或者为 Opensource.com 撰写文章。但是开始写作说起来容易做起来难。我听到的不写作最常见的两个借口是：“我没有什么新内容可说”和“我不是一个好的作家。”我在这里是为了消除这两种误解。

你应该写些什么？

“寻找那些经常被遗漏的故事。”

—Erik Larson

对于某些人来说，写作的最大障碍是产生写作的想法或主题。人们很容易陷入这样的误区：“这个主题已经被写过了，所以何必再写呢。”

我不是第一个写关于写作文章的人，也不会是最后一个。我带来的是我独特的视角和我多年来学到的东西。有人向我询问关于如何开始或如何提高写作水平的技巧。我决定将这些建议变成一篇文章。

你的写作是你自己的反映。没有人会像你一样讲述故事。你的经验和视角可能正是其他人所需要的。

这里有一些提示可以帮助您想出主题

最近你学到了什么？写下你是如何学习的，你学到了什么，或者什么让你感到惊讶。
你经常被问到哪些问题？写下答案。
你最近是否搜索过操作指南文章，但对任何热门搜索结果都不满意？写下你正在寻找的文章。
你参加过会议或研讨会吗？写一篇关于你所学内容的会后总结。
你开始使用新工具了吗？写一篇操作指南或入门指南。

你正在写哪种类型的文章？

有不同类型的写作，包括

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

内容类型将影响您的写作风格和语气。博客更非正式和对话式。技术文档更正式和指导性。

你是为谁写作？

每篇写作都应该有一个单一的受众。受众是您为之写作的那种人。在您开始写作之前，写下读者的一些特征会有所帮助。重要的是要考虑您为谁写作，以及您不为谁写作——确定您的目标受众将决定包含什么和不包含什么。

例如，这就是我在撰写这篇文章时设想的读者

具有写作和语法的基本知识
对提高写作技巧感兴趣
在技术领域工作，担任开发人员、销售工程师、客户成功经理或类似角色
不是经验丰富或高级的作家，可能在个人或工作博客上发表过几篇文章，并且想要写更多
正在写非小说类作品

如果您有针对多个受众的内容，请考虑将其分解为针对不同受众的不同部分。在您的受众中需要考虑的一些方面

专业知识水平：新手、中级、高级
角色：经理、个人贡献者
目标：他们为什么阅读？

文字很重要

您选择的词语将对读者产生影响。难词会使文章更难理解。不熟悉的词语会让读者感到愚蠢。某些词语可能会意外地冒犯读者。作为一名作家，您的目标是避免所有这些。以下是如何做到。

使用日常语言

不要为了炫耀你的词汇量或从你的“每日一词”日历中学到的词语而写作。写作是为了让读者能够理解。每篇写作都与阅读水平相关。如果您正在编写技术文档，请以大约八年级的阅读水平为目标。这并不意味着您的受众只有八年级的教育水平。这意味着您的写作将更容易理解。您是希望人们纠结于语言，还是希望他们离开时感觉自己学到了一些东西？仅仅因为您可以使用大的、复杂的词语，并不意味着您应该这样做。使用简单的语言并不一定意味着您的文章会很无聊。

使用 Hemingway App 等工具来检查您写作的可读性（它不是开源的，但非常出色）。例如，在初稿之后，本文被评估为五年级的阅读水平。Hemingway 还提供了关于如何改进您的写作的建议——识别难以阅读的句子或更改措辞的地方。

如果您在想不出替代词时遇到困难，请查看 Plain English Campaign 的建议或 Power Thesaurus 的众包建议。

知道要避免哪些词

“每次你想写‘very’时，都用‘damn’代替；你的编辑会删除它，而写作就会恰到好处。”

—马克·吐温

在编写教程或操作指南时，以下是一些要避免使用的词，包括“simple”、“easy”和“just”。您，作为您正在撰写的主题的专家，在多年的实践后可能会发现事情很容易。初学者可能不会觉得事情简单或容易。您的读者可能会感到沮丧，因为他们觉得过程或解释不简单。

您是否曾经不得不反复阅读一个句子或段落，因为您无法弄清楚作者在说什么？您是否曾经因为一篇文章对您来说没有意义而放弃它？我有过。

作为一名作家，您希望您的读者感到困惑或不聪明吗？我希望不是。

您写作中要避免的其他词

That
Really
Very
So
In order to

通常，可以删除这些词语而不会改变句子的意思。

完成写作后，我会搜索文档中这些词语的实例。当我搜索本文档时，我发现了以下句子

“这并不意味着您的受众只有八年级的教育水平，而是意味着您的写作将更容易理解。”

句子中出现了两次“that”。它们没有为句子增加价值。可以删除它们而不会改变其含义。删除这些实例会缩短句子，而较短的句子更容易理解。说到较短的句子，我也将其改写为两个句子。

“这并不意味着您的受众只有八年级的教育水平。这意味着您的写作将更容易理解。”

使用包容性语言

词语和短语的历史背景可能导致人们感到被排斥或冒犯。写作时，您希望让读者感到被包容。当您使用包容性语言时，它会让您的读者感到被理解、被尊重，并且有归属感。我参考了 Buffer 的这篇关于使用包容性语言的指南。

修订和编辑

“几乎所有好的写作都始于糟糕的初稿。你需要从某个地方开始。”

—安妮·拉莫特

写作是一个迭代过程。如果您认为作家坐在办公桌前，在一小时内就完成了一篇准备发表的文章，请再想一想。有些文章我需要花费数周才能完成。这是我的标准流程

编写粗略的初稿。我说的粗略，是指非常粗略。我写作时不担心语法。目的是将我脑海中的文字写到纸上。此步骤可能需要一小时到几周的时间。
将草稿放置一段时间。这可能是几个小时到几天，具体取决于发布时间表。
审查草稿。进行调整和编辑。
征求反馈，无论是来自同事还是朋友。在反馈的这个阶段，我专注于清晰度。一切都说得通吗？有什么令人困惑的地方，有什么遗漏的部分吗？
采纳反馈。无论您的写作经验多么丰富，其他作家审查您的作品都会使其变得更好。

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

我的写作挑战之一是恰当地使用逗号。Grammarly 帮助我找出我遗漏或误用逗号的地方。Grammarly 识别出与本文最终草稿的正确性相关的 43 个问题。大多数是逗号错误。