你好。很高兴你能来。让我自我介绍一下。我是 Anne Gentle，OpenStack团队最新加入的一员。我迫不及待地想开始工作，简直难以自持。我已经潜伏了一段时间，现在是时候揭示我的角色了——我是OpenStack的技术文档编写员。
我如何来到这里？几年前我开始参与开源项目，并乐于运用我的技术沟通技能，因为开源项目通常存在文档和支持方面的不足。我成为了 FLOSS Manuals的坚定支持者，在那里我们为自由软件编写免费手册。我们使用wiki和 Booki，一个新型的协作写作平台。我们还采用“书冲刺”技术，将协作写作的努力集中在一周的冲刺中。我曾帮助过几次书冲刺，认为这是一种很好的开源文档技术。
接下来我该怎么办？今天我想开始概述一些文档策略，以获取你的反馈并进行调整。我们将会在实践中测试文档工作，并可能从对象存储领域开始。
审计与分析
这个阶段应该回答诸如，已经存在什么以及它的表现如何？我计划立即进行一次全面的内容审计。看起来有很多地方可以记录信息，我想确定有哪些内容。我已经开始阅读 Swift文档，并了解 Sphinx。我们都在技术领域摸爬滚打了一段时间，知道工具并不是完整的解决方案，而是创造者和工匠帮助内容从足够好到卓越。
我也会研究其他项目（我已经观察了几个不同的项目一段时间了）。我也想听听你的偏好——你如何从类似的项目中获取信息？
在这个阶段还需要进行受众分析——谁需要文档，以及他们用它来完成什么任务？我预计会优先考虑管理员文档和开发者文档，以及对OpenStack进行初步了解的人员的入门信息。
行动
- 在wiki上建立一个表格，显示内容存在的位置。
- 寻找可重用机会以及统一的特征，例如受众、难度级别、分块和内容组织。
- 描述典型的读者以及他们需要完成的任务。
创建与协作
在分析阶段之后，我会避免分析瘫痪，我想看看内容结构——应该创建哪些类型的信息，以及在哪里可以找到它们？信息类型化是我作为一名作家更容易和更有组织性的重要组成部分。Jacob Kaplan-Moss写了一篇关于编写有效文档的精彩文章，详细介绍了应该写什么。我完全同意你可以用教程、专题指南和参考指南来编写任何技术文档。我相信这种方法将帮助我们编写有帮助、有用的文档。我想将文档构建为社区精神的一部分，是我们重视的东西的一部分。
乍一看，所需文档的类型可以很容易地按读者划分——开发者文档（可以与Sphinx一起存在于Python代码中，存在于Launchpad的规范中，以及在需要实时协作时存在于Etherpad中），以及管理员文档（可以存在于wiki上，尚未确定）。我们总是要考虑翻译和本地社区支持，因为不以英语为母语不应该阻止你为文档做出贡献。
行动
- 为文档创建一个Launchpad，用于请求和跟踪。
- 为OpenStack wiki创建一个入门样式指南。
- 与感兴趣的各方谈论贡献。
- 在wiki上设置入门模板。
- 尽可能多地编写和编辑。
- 计划针对特定主题的文档冲刺，与线下活动同时进行。
目标
我认为文档应该首先支持用户。对我来说，实用的、可见的结果是第一位的，花哨的解决方案是第二位的。我认为这种理念在Rackspace非常有效，很高兴看到它是一个核心价值——结果第一，内容重于形式。
你觉得呢？你认为OpenStack技术文档的目标应该是什么？支持？采用？教育？以上所有？请告诉我们。
你能做些什么来帮助文档？
请把我介绍给那些想要好的文档并认可好的文档的人。介绍你自己或提名其他人。发送给我一些做得好的网站的例子。在进行过程中记录下来，即使是粗略的笔记。帮助我们制定文档策略，使其适合我们的社区。
你可以在我的博客 JustWriteClick.com上了解更多关于我的信息，在Twitter上 @annegentle，并通过多种方式与我联系——评论我的帖子，在Twitter上与我交谈，或通过电子邮件anne at openstack dot org与我联系。
我会开始提很多问题，但这些是我的初步想法。准备好开始堆叠了！
发表回复