文档撰写在开发中的作用
我大约在18个月前（即2018年4月）写了我作为开发人员的第一篇文章 。从那时起，我已经阅读并撰写了大量文章。
但这并非一帆风顺。
作为开发人员，这些文章是我们生活中最重要的部分之一，仅次于StackOverflow，咖啡和比萨饼。
这些文章有助于我们
- 学习新的工作内容。
- 乱砍东西，然后吹牛。
- 解决方法或解决关键问题。
- 生活课程，灵感和许多其他东西……
我大部分时间都花在前三件事上。 大家都这样做。 硬道理是，我们在它们上浪费了很多时间。
说真的，很多时间。
这并不意味着文章不好。 他们只是当今大多数开发人员文章所面临的常见问题的受害者。
是的，我的文章也是同一个故事……
阅读大量文章后，我发现大多数文章都面临四个主要问题。
问题1：维护狂热
就像这个世界上的一切一样，文章的生命也很有限。
我们维护汽车，房屋和笔记本电脑的寿命。 但是，大多数作者在撰写文章时都忘记了这一点。
可以以多种形式发生此问题：
自发布之日起，本文中就有一些错误的代码示例。发布时，该示例被视为GOLD。 但是随着时间的流逝，这些代码示例不再起作用，现在许多其他文章以及您的朋友都引用了该文章。 现在唯一要做的就是浪费人们的时间。 很多时间。很多时候，作者对发现本文中有错误的读者的询问和评论不予答复。是的，有时我也是其中之一...
但是我确实为他鼓掌。
最终，这些文章变成了漂浮在广阔数字空间中的碎片，损害了作者的声誉和读者的时间。
问题2：经验的海平面
随着全球海平面的变化，开发商之间的经验水平也各不相同。
当我们希望我们可以像下面那样复制终端命令时，我们所有人都会经历一个开发者生命的阶段，并且它会起作用。
我们大多数人还复制了$符号，并想知道为什么我是唯一发现此bug的人？
随着我们进入更详细的教程，这个问题变得更加严重。 由于文章的篇幅，我们的作者有必要跳过这些小细节，不幸的是，新手很难弄清楚。
问题3：错误：上下文未定义
我们都使用不同的操作系统，不同的代码编辑器，不同的浏览器等等来不同地关注文章。
这使得作者很难涵盖可能会失败的所有极端情况。
即使作者能够解决当今的所有极端情况，但由于事情经常发生变化，即使您花了很多时间检查所有极端情况，您的代码示例也很有可能不会长期存在。
问题4：文章！=过山车
开发人员教程可能很长。 痛苦的冗长。
作为负责任的作者，我们大多数人都试图使我们的文章充满趣味性和吸引力，并包含所有的模因和电影参考资料，如果您没有看过特定的电影，其中的一些则毫无意义。
另外，使用当前平台很难在您的文章中引入游戏化。
因此，很多读者更喜欢找到TL; DR的说法
这是包含所有代码的Github存储库…
而不是阅读整篇文章。
如果没有正确组织教程的内容，则会导致大量重定向到Github存储库。 这对您的GitHub项目很有用，但对您的文章不利。
顺便说一下，正如我主要撰写的有关Web 3.0的文章一样，以上所有这些问题对我来说都变得越来越糟。
由于Web 3.0是一个新社区，因此事情经常发生中断，使我的文章寿命更短。 当涉及到体验时，受众分布不均。 Web 3.0的学习曲线使情况变得更糟。
在这里，上下文的重要性比以往任何时候都重要，因为大多数库被少数OS /浏览器选择性地支持。
当您认为自己的问题已经解决时，文章的篇幅就变得很长（由于学习曲线和设置要求），以至于我很难一口气阅读它，更不用说听众了。
我试图找到一些可以帮助我解决这些问题的东西。 但是没有运气。
因此，当我启动SimpleAsWater来简化在Web 3.0上的开发和学习时，我承诺还将建立一个讲故事的平台，该平台着重于开发人员的需求。
在接下来的几周内，我们将针对以开发人员为中心的讲故事平台开始一个私人的Beta测试。 您可以申请成为我们的 前100 名将测试该平台的人员。
同时，让我向您展示一些我们正在构建的内容。
解决方案1：将CI / CD应用于您的文章
在进行代码维护时，CI / CD是软件开发中的事实上的标准。 对于我们开发人员而言，代码示例是本文最重要的部分之一。 那为什么不为您的文章提供CI / CD？
这看起来真的很复杂。 但是我们在这里使其变得简单。
我们会对您的代码示例进行常规CI测试，以确保它们仍然有效。 如果发现有鱼，我们将把损坏的细节寄给您。
这使每个人都可以轻松维护您的文章。
解决方案2：如何寻求他人的帮助？
今天，如果我们在阅读文章时被困在某处，通常会发表评论以寻求帮助。 您的评论很容易在众多“谢谢”评论中迷失。
因此，我们正在引入一个“帮助”评论，该评论将向正在阅读本文相同部分的每个读者突出显示。 这样，您的疑虑就可以轻松被发现。
解决疑问后，将记录帮助注释和选择的答案。 每当有人在同一部分中寻求帮助时，都会向他/她显示以前的“帮助”注释，该注释可能类似于他/她想要询问的内容。
解决方案＃3：文章= Git存储库
大多数文章不会长时间保持活跃。 您的未跟踪代码也是如此。
我们将您的文章视为公共git存储库，人们可以在其中添加问题并提交PR。
听起来复杂吗？ 不用担心，一切都将在幕后进行。
这将有助于作者更轻松地与受众互动，并为受众提供帮助作者维护其文章的能力。
另外，它使我们可以轻松地对您的文章进行CI / CD。
解决方案＃4：定义上下文
我们尝试将所有人置于同一页面上，而不是每个人都遵循不同的路径（使用不同的操作系统，浏览器来运行代码）。
为此，我们提供了一个内置的代码编辑器。 基本上，您可以在文章中嵌入实时VS Code编辑器，每个人都可以在同一环境中尝试相同的代码。
解决方案5：内置游戏化和娱乐支持
使您的内容引人入胜和有趣的最大部分之一就是以一种很好的方式组织和显示您的内容。
因此，除了增加对内置模因的支持之外，我们还提供了所谓的“步进器”。
以下是一些有关它们外观的示例。
使用“步进器”，您不仅可以组织您的内容，还可以选择锁定文章的各个部分，只有当您完成特定部分时，该部分才会被解锁。
如果有人只是对教程的特定部分感兴趣，您还可以添加一个传递步骤的选项。
您也可以选择使“步进”垂直。
我们还为您吸引了移动受众。
还有更多可定制的选项。
解决方案＃6：保持简单
我们提到了很多功能。 这可能会导致您问
所有这些都不会使撰写文章变得太复杂吗？
那是很明显的。
但这是我们在SimpleAsWater的座右铭，使事情变得容易而不是困难。
我们正在开发一个直观的UI / UX，它将提取过程的所有复杂性，使您有写SimpleAsWater文章的经验。
解决方案7：有何建议？
如果您有任何想法/建议，请告诉我们。
让我们建立一个强大的社区
我们可以建立任何我们想要的东西，但是如果我们没有一个友好的社区，那将毫无用处。
关于作者
Vaibhav Saini是TowardsBlockchain （ 麻省理工学院剑桥创新中心孵化的初创公司）的联合创始人。
翻译自: https://hackernoon.com/how-to-write-better-posts-as-a-developer-fu11o2zco
文档撰写在开发中的作用
2667
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
