docs和src

想象一个房间里到处都是聪明，有趣和古怪的人，他们都喜欢文档，技术和……食品。 将所有内容放在一起，您便可以在波特兰编写文档 （WTD），这是一个社区会议，记录员开会讨论我们最喜欢的事情。

阅读文档的直接后代

WTD是Read Docs的直接后代， Read Docs是托管开源软件文档的网站。 由于WTD起源于开放源代码运动，因此它对各种职位开放，这些职位都关心文档和清晰的沟通。 今年，我们有质量保证人员，图书馆员，软件开发人员，当然还有技术作家和编辑，其中还包括一些用户体验（UX）人员。

去年是我参加会议的第一年，我感觉好像刚走进一个充满我最亲密朋友的房间。 如此Swift地适应某个地方真是令人震惊。 大部分的舒适感是由于会议的“吃豆人”规则所致：如果您站在一群人中，请始终在圈子中留出空间让另一个人跳进来。像“吃豆人”一样站立，准备邀请一个新朋友加入并受到欢迎。

^{总是为新朋友留出空间。}

WTD波特兰2017发生了什么

编写类似代码的文档

2017年会议的流行语是编写类似code的文档 。 这实际上是什么意思？ 它是综合的，部分意味着要使用Git存储库或类似的代码管理系统来处理和格式化原始文本。 这也意味着，在理想的情况下，如果您要编写代码之类的文档，则文档和代码都存在于相同的存储库中。 开发人员和专业作家都可以轻松地改进文档并做出贡献，从而使这两个世界之间没有障碍。

正如Jodie Putrino在演讲中所说的：将文档视为代码：实践帐户 ：“我们现在都是文档编写者。”

编写更好的技术文档的3个技巧

在WTD Portland 2017上，我们还听到了很多有关如何改进文档的信息。 这是三个重要提示：

• 使用极简主义和任务分析之类的技术写作技巧，使您的文档更清晰，更好。
• 加强您与支持人员的关系，以改善您的文档和他们的生活。
• 注意您的读者并为他们写作。

最后，Amelia Abreu撰写的《 关怀系统：作为护理的文档》谈到了我最喜欢的两个主题：人种学用户访谈和可用性测试。 作为人类学家和经验丰富的用户体验（UX）顾问，我对这两种技术的推荐不够高！

4个推荐的演讲

转至YouTube上的Write the Docs 2017频道 ，查看所有精彩的演示文稿。 我最喜欢的一些是：

• 错误消息：谦虚，人性化和乐于助人 Kate Voss。 她解释了如何定制您的错误消息，以使其周到且真正有用。
• 即使是命名该演讲 ，Ruthie BenDor 也很难 。 她举例说明了在她的工程师职业生涯中遇到的几个可怕，可怕，不好，非常糟糕的名字，并谈论了如何改善命名。
• 从任务开始，而不是 Sarah Hersh 的终点 。 她通过采访客户和进行调查来介绍有关创建面向任务的API文档的过程的案例研究，最后以迭代文档设计为结尾。
• 人群的智慧：我在开放组织中将极简主义进行众包 。 我在Red Hat的部门正在众包撰写评论，以传播新的文档方法。 我的演讲描述了我们的方法，并解释了众包和极简主义。

为出色的志愿者鼓掌

今年，我提出并不得不解决技术难题，但是WTD志愿者聚集在一起进行我的介绍工作的方式非常出色。 他们牺牲自己，使我的演讲成为可能。 会议主持人尼克·布兰奇 （ Nik Blanchet ）将我的大部分演讲都像一个柔术表演者一样弯曲在膝盖上，为我推进幻灯片。 多么惊人的一群人！

翻译自: https://opensource.com/article/17/7/write-the-docs-portland-2017

docs和src