kibana 创建文档_创建世界一流技术文档的7条规则

最新推荐文章于 2024-04-03 10:04:48 发布

cumo3681

最新推荐文章于 2024-04-03 10:04:48 发布

阅读量95

点赞数

文章标签： java 人工智能大数据 python 编程语言

原文链接：https://opensource.com/business/16/1/scale-14x-interview-bob-reselman

版权

kibana 创建文档

在2016年南加州Linux Expo（SCaLE 14x）上，长期的技术作家兼编辑Bob Reselman将发表名为“创建世界一流技术文档的7条规则，v.2016”的演讲，该演讲基于他撰写的文章超过六年前。在这次采访中，他提供了规则的更新，并讨论了对项目文档的态度是如何变化的。

如果您今天是第一次写文章，那么您是否具有创建世界一流技术文档的7条规则？还是自那时以来制定了规则？

好，这是7条规则：

干烂。
在开始之前，请清楚结束后希望读者做什么。
始终写出结构良好的轮廓。
避免模棱两可的代词。
清晰度=插图+文字
处理概念时...逻辑说明和示例。
接受修订。

对我而言，最进化的规则是＃1：干烂。最初编写规则时，我是幽默的大力拥护者，以此作为避免干燥的一种方式。我已经演变为认为引人入胜的内容会使工作不枯燥。是的，我们中有些人仍然喜欢幽默。但是，我做的越多，我越发现使用具吸引力，准确，易懂的插图的清晰，反复的文章可以避免技术文档领域的诸多枯燥乏味。

您在开源项目文档中看到的最常见错误是什么？

这对我来说很难回答。好事多于坏事。我认为Read.ME文件的重要性和突出性以及降价促销使一致，有用的技术文档成为开发社区的一种生活方式。是的，过时了，这对于任何文档都是很普遍的，但是无论如何，基于文本的文档中的所有事物都在上升。

哪些项目具有出色的文档能力？哪些将从文档检修中受益？

我不能真正指出任何一个项目，因为有很多项目。但是就商业工作而言，我认为New Relic的人们做得对。它们具有结构良好的分类法，并具有支持它的内容。该公司制作了简短有用的视频，这些视频很准确。

Akka.Net的工作也很出色。文本文档在视觉上清晰且井井有条。文档的每一页在左边缘显示大纲组织，因此您可以通读或选择。他们显然已经计划了事情。他们致力于使人们尽可能容易地使用他们的技术。

当然，就能够呈现大量文档而言，您必须佩服AWS所做的工作。关于HowTo，在UI的视觉显示方面还是有些不足，但是总的来说，他们确实设法捕获并呈现了一个非常有用的巨大分类法。

这些年来，您是否对项目文档以及编写文档的人的态度有所改变？

对于大公司和工具提供商，文档总是在不断完善。这种情况的经济性要求他们尽一切努力使用户群满意。但是，对于中小型公司，尤其是那些拥有IT部门而不是软件开发部门的公司，我没有看到我希望获得的进步。任何生产软件或系统的公司都应聘请技术编辑人员这一观念仍然很难推销。希望是有一天他们会聘请一位唯一的技术作家来使一切变得更好，或者他们希望软件开发人员当前的文档工作足够好。确实，所有内容创建都需要由主题专家生成，但是好的技术编辑人员可以教会内容创建者如何提高效率。而且，技术编辑者了解全局，需要满足的知识库的总体分类以及使工作在短期和长期内保持一致所需的样式准则。

然后，视频作为文档资源不断出现。我将在2016年7条规则演讲中谈论视频。有很多工作要做。