因为收到越来越多期望实现DOCASCODE文档代码化的客户请求，我花费时间去深入学习和了解DOCASCODE主要驱动组件GitHub。本文与您分享了GitHub高级产品总监KathyKorevec文章，期望对您认识和改善产品文档提供有意义的启发。

你可能听说过这样的事情之前，“文档是不是一个优先事项，我们复制和使用什么别人已经建成的文档不就可以了吗？”文档通常是事后的想法，不仅在功能实现方面，而且在写作和策划方面也是如此。事实是，文档可以成就或破坏某人使用您的软件的成功。通常，开发人员通过文档形成他们的第一印象，甚至在他们制作产品之前。通过个性化的引人入胜的体验使文档栩栩如生，可以成为陈旧、深奥的文档的解药。构建充当产品管家的文档。

今天，太多的文档站点是静态的、过时的和毫无生气的。尽管它们通常是核心产品，但他们并没有像核心产品那样认真细致地考虑它们。预计读者会做太多的工作，一个接一个地打开一个标签，无休止地搜索并滚动冗长的文章，只是为了找到一个简单的代码示例。

如果文档知道您正在Windows机器上编写Python应用程序并且您更喜欢观看视频而不是通读文本，那不是很好吗？我希望您可以轻松高效地在文档中找到问题的答案。当您遇到问题并转向文档时，当您找到解决方案时，会有一个神奇的时刻，尝试一下，它就起作用了。在那一刻，你变得畅通无阻，你学到了一些新的东西，你可以继续构建你的应用程序。

在过去的一年里，我一直在GitHub与我们的文档团队一起工作，在那里我们一直在共同努力了解开发人员今天在文档方面面临的挑战。我们希望打造一种更好的体验，激发更多灵感，教导而不是假设，减少混淆，并根据您作为开发人员的需求进行个性化。我们一起学习了一些关键的东西，这些东西帮助我们理解了开发人员每天面对文档的一些痛苦：

人们很难找到他们需要的东西：文档没有从产品中的正确位置链接。

支持团队依赖于复制文档而不是引用文档的知识管理系统(KM)—专注于内容存储、检索和评估（而不是最终用户的成功）。

开发人员通过许多不同的方式学习不同的东西——教程、视频、示例、指南等。今天的文档主要提供静态内容和非交互式代码示例。

人们使用搜索作为一种导航方式，当他们深入阅读一篇文章时，他们经常会丢失搜索用户体验。

当开发人员遇到困难时，他们想向其他开发人员提问并从同行那里得到答案。

顺便说一句，如果我们解决了这些痛点，不仅可以让阅读和与文档交互的体验更好，而且我们还可以提高编写文档的体验。如果您有幸拥有一群了不起的技术作家，就像我们在GitHub所做的那样，那么重要的是利用他们对产品的深入了解，并为他们提供编写出色文档的工具。我们在年10月开源了整个GitHubDocs应用程序，这包括内容、代码，甚至是撰写文章的过程。对于以协作、身临其境的方式编写的系统，我们必须构建与之匹配的用户体验。

在与数百名开发人员交谈，了解他们正在努力解决什么问题以及他们的愿望之后，我写下了一些原则。目的是有一些可以依靠的东西，我可以在集思广益的想法时使用它，这些想法可能会解决开发人员对文档的一些挫折。

以代码为导向：开发人员想编写代码，给他们代码示例作为起点。不要埋葬lede。

解决问题（又名：回答问题）：开发人员访问文档以了解他们试图解决的问题、挑战或问题的答案。通过多种方法（视频、文本、教程、指南等）为他们提供答案，以便他们以适合他们的方式学习解决方案。

赋能社区：拥抱协作的乐趣、社区的支持，并赋予人们教学的权力。

满足用户的需求：永远不应该优化文档以产生支持票，我们不会让开发人员打开票，我们确保我们的内容满足用户的需求。

鼓励贡献：开源——任何人都应该能够为文档做出贡献并帮助改进内容。

保持文档新鲜：软件更改，文档也应更改！他们应该感觉活着、新鲜和相关。

优化和简化：简单很难实现，我们不断优化和简化我们的平台和对内容的访问——最大限度地减少对内容的点击。

可衡量的成功：我们正在积极衡量我们的内容是否成功满足用户的需求并不断提高其功效。

鼓励游戏和实验：开发人员来文档做很多事情，让他们通过玩弄来发现和创造性地参与。“你自己试试！”

中等不可知性和便携性：开发人员应该能够从他们所在的任何地方调用文档，比如他们的终端或他们的IDE。代码示例应该易于携带和重复使用。

我对这些草图的目标是为我们如何将文档带入一个更加社区驱动、开发者优先、可扩展和互动、引人入胜的世界设定方向。这个想法是它们是中等不可知的（开发人员可以从任何地方调用文档），它们是开源的（任何人都可以轻松地为文档做出贡献，这意味着更新我们的发布过程），并且它们作为软件内容（我们将内容视为软件开发过程的一部分，而不是次要的）。

我想从一个专注于我们内容平台简洁性的系统转变为一个同时强调开发人员试图做的事情背后的意图的系统。当您查看其他学习和内容系统（如Stripe、Twilio或CircleCI）时，它们会围绕意图模型构建内容。例如，“开始使用Stripe的API”，在进入时确定内容的意图，这使开发人员在探索和学习时掌握了权力。

这些草图旨在帮助我们的用户更快地到达正确的地方，并迫使我们作为策展人思考读者想要做什么——我们可以根据意图而不是简洁来构建。

最后，他们引入了一个系统，我们可以在探索和开始构建时对其进行扩展。所以，有一些事情我故意没有

转载请注明:http://www.aideyishus.com/lktp/2599.html