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

图片来自

原图由 jetheriot 拍摄。 Rikki Endsley 修改。 CC BY-SA 2.0。

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

你应该写些什么？

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

—Erik Larson

对于某些人来说，写作的最大障碍是产生一个想法或主题。很容易陷入这样的陷阱：“这个主题已经被写过了，为什么还要麻烦呢。”

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

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

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

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

你正在写什么类型的文章？

有不同类型的写作，包括

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

内容的类型将影响你的写作风格和语气。博客更非正式和口语化。技术文档更正式和说明性。

你为谁写作？

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

例如，这是我写这篇文章时设想的人

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

如果你有针对多个受众的内容，请考虑将其分解为针对不同受众的不同部分。一些需要考虑的受众领域

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

文字很重要

你选择的文字会对读者产生影响。难懂的词语会使文章更难理解。不熟悉的词语会使读者感到愚蠢。某些词语可能会意外地冒犯读者。你作为一名作者的目标是避免所有这些情况。这里是如何做到这一点。

使用日常语言

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

使用像 Hemingway App 这样的工具来检查你的写作的可读性（它不是开源的，但它很棒）。例如，在初稿之后，这篇文章被评估为五年级的阅读水平。 Hemingway 还提供关于如何改进你的写作的建议——识别难以阅读的句子或改变词语选择的地方。

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

知道要避免哪些词语

“每次你想写‘非常’的时候，都用‘该死’代替；你的编辑会删除它，而写作就会和它应该的一样好。”

—马克·吐温

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

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

作为一名作者，你是否想让你的读者感到困惑或不聪明？我希望不是。

其他要避免的词语

那个
真的
非常
所以
为了

一般来说，这些词语可以在不改变句子含义的情况下被删除。

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

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

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

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

使用包容性语言

词语和短语的历史背景可能会导致人们感到被排斥或受到冒犯。在写作时，你希望让读者感到被包括在内。当你使用包容性语言时，它会使你的读者感到被理解、被尊重和像他们属于这里一样。我参考了 Buffer 上的这篇关于使用包容性语言的指南。

修订和编辑

“几乎所有好的写作都始于糟糕的第一次尝试。你需要从某个地方开始。”

—安妮·拉莫特

写作是一个迭代的过程。如果你认为作者坐在他们的办公桌前，并在一个小时内完成了一篇准备发表的文章，那就再想想。有些文章需要我几周才能完成。这是我的一个标准流程

写一个粗略的初稿。粗略的意思是粗略。我写作时不担心语法。其目的是将文字从我的脑海中取出并写在纸上。这一步可能需要一个小时到几个星期的时间。
将草稿搁置一段时间。这可能是几个小时到几天的时间，具体取决于发布时间表。
审查草稿。进行调整和编辑。
寻求反馈，无论是来自同事还是朋友。在这个反馈阶段，我关注的是清晰度。一切都有意义吗？有什么令人困惑的地方，有什么缺失的部分吗？
融入反馈。无论你的写作经验多么丰富，其他作者审查你的作品都会使它变得更好。

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

我的一个写作挑战是适当地使用逗号。 Grammarly 帮助我弄清楚我在哪里遗漏或滥用了逗号。 Grammarly 识别出 43 个与这篇文章的最终草稿的正确性相关的问题。大部分是逗号错误。