也许是时候我们重新想到了文件

GitHub Docs是开源的，您可以通过访问GitHub repo来贡献项目。

你可能之前听到了这样的事情，“文档不是优先事项，我们不能只是复制并使用其他人建造并打电话完成的东西？”文档通常是一个陆续的思想，不仅在特征实施中，而且还在写作和策划。事实是，文档可以用软件制作或打破某人的成功。通常，开发人员通过DOCS形成他们的第一次印象，即使在他们将其交给产品之前也是如此。用个性化的参与体验为生活带来文件可以是陈旧的解剖学博客的解毒剂。构建充当产品的Docs。

今天，太多的文档网站是静态，过时的，无生命。它们并没有以为与核心产品相同的护理和细节，即使它们通常是核心产品。读者预计会在选项卡后打开选项卡，无休止地搜索并通过详细滚动以查找简单代码示例。

如果文档知道您在Windows机器上编写Python应用程序，并且您首选观看视频而不是通过文本读取的读数我希望您能够轻松敏捷地找到文档中的问题的答案。当你被困在一个问题并且转向文档时，当你找到解决方案时，有一段魔法，试试吧，它的工作。在那一刻，你变得畅通无阻，你学习了一些新的东西，你可以继续继续建立你的应用程序。

在过去的一年里，我在GitHub上度过了我们的文献团队，我们一直在努力了解开发人员今天面对的挑战。我们希望建立一种更好的经验，鼓励更多，教导而不是假设，混淆，并且是您作为开发人员的个人方式。我们一起学习了一些有助于误解一些痛苦开发人员的关键事情，每天都有一些痛苦的开发者面对：

人们很难找到所需的东西：文档没有与产品的正确位置相关联。

支持团队依赖于知识管理系统（KM），该系统重复文档而不是引用它们 - 专注于内容存储，检索和评估（而不是最终用户的成功）。

开发人员在许多不同的方式中了解不同的东西 - 教程，视频，示例，指南等。Docs今天主要提供静态内容，其中代码示例不是不交互的。

人们使用搜索作为导航的方式，当他们深入一篇文章时，他们经常丢失搜索ux。

当开发人员陷入困境时，他们想询问其他开发人员的问题＆amp;从他们的同龄人那里得到答案。

顺便说一下，如果我们解决这些痛苦点，我们不仅是更好地读取和与文档互动的经验，而且我们还能够提高写作文档的经验。如果你很幸运有一个惊人的技术作家，就像我们在GitHub一样，很重要的是利用他们对产品的深刻了解并为他们提供了编写伟大文档的工具。我们在2020年10月开放了整个GitHub Docs应用程序，其中包括内容，代码，甚至是创作文章的过程。通过以合作，沉浸方式撰写的系统，我们必须建立用户体验来匹配。

在与数百名开发人员交谈后，学习他们正在努力的东西，以及他们希望的，我写了一些原则。意图是为了有一些东西可以依赖，我可以随着我的头脑风暴的想法，这些想法可以解决一些挫折开发人员的文件。

带代码：开发人员想要编写代码，将代码示例提供为起始块。不要埋葬lede。

解决问题（AKA：回答问题）：开发人员来到文档，以了解他们试图解决的问题，挑战或问题的答案。通过多种方法给予他们答案（视频，文本，教程，指南等），因此他们以适用于它们的方式学习解决方案。

启用社区：拥抱合作的乐趣，社区的支持，并赋予人们教人的人。 符合用户＆＃39; s需要：文档不应优化，导致支持票证，我们不漏斗开放式票证，我们确保我们的内容符合用户的需求。 鼓励贡献：开源 - 任何人都应该能够为Doc＆amp做出贡献; 帮助提高内容。 保留文档新鲜：软件更改，所以文档应该！ 他们应该感到活着，新鲜和相关。 优化和简化：简单难以实现，我们一直融合并简化我们的平台并访问内容 - 最大限度地减少点击内容。 可衡量的成功：我们正在积极衡量我们的内容是否成功地满足用户需求，并始终如一地提高其疗效。 鼓励戏剧和实验：开发人员来到Docs做很多事情，让他们通过游戏来源地发现并创造性地参与。 “自己试试！”

媒体无症状＆amp;便携式：开发人员应该能够从他们的终端或其IDE等任何地方调用文档。代码示例应该很容易随身携带并重新使用。

下一部分是一个小偷看了产品人的大脑。以下是一系列想法 - 其中一些是对GitHub的文档引起实际改进，但我用它们作为一种引发好奇心的一种方式，并为我们如何为开发人员构建更好的文档而生成想法。

我与这些草图的目标是为如何将文档带入更多的社区驱动，开发者 - 第一，可扩展和amp;互动，吸引世界。这个想法是他们是中等无人机（Devs可以从他们所在的地方调用Docs），他们是开源的（任何人都可以轻松为文档做出贡献，这意味着更新我们的发布过程），它们是软件的内容（我们将像软件开发过程的一部分对待内容，而不是次要的）。

我想从一个系统中搬到一个专注于我们的内容平台的简洁到一个也突出显示开发人员正在努力的内容的一个系统。当您查看其他学习和内容系统，如条纹，零线或圆形CI，它们会使意图模型周围的内容构成。例如，“开始使用条带的API”，确定进入内容的意图，将电源放入开发人员的手中，因为他们探索和学习。

这些草图旨在帮助我们的用户更快地进入正确的地方，并强迫我们作为策展人思考读者正在尝试的事情 - 我们可以基于意图构建，而不是简洁。

最后，他们介绍了一个系统，我们可以在我们探索和开始建立它时扩展。所以，有一些我故意专注的东西，但我们需要在某些时候解决，因为它们很重要：

我始于教程或指南的文章页面。我首先选择它，因为开发人员经常在看到这些网站的任何其他部分之前了解这些页面，而且感谢推荐链接和Google搜索。

此页面背后的想法是尽可能快地将读者进入内容，以便他们可以尝试并自己尝试。该页面分为三部分：左侧浏览教程步骤，突出显示代码示例的正确交互框，底部告诉您接下来的位置，如果您感觉宽容要求反馈。页面中最重要的部分：互动。

我与文档交谈的开发人员总是告诉我他们主要互相学习。有时它是通过代码审查，其他时间是通过谷歌曲和阅读其他开发人员的例子。将此反馈取向心脏，我决定与您在文档本身内有关软件或代码的对话。

文档是关于学习，人们在很多方面学习。你只有一种方式学习的想法一直似乎是我的小香蕉。有时我是一个听见的学习者，有时我是视觉的。拥抱那个，以及让文档生命的欲望一点点，我决定添加一些视频。

此页面与使用代码示例的文章/教程页面类似。如果您宁愿观察有关内容的视频，请单击“视频”选项卡并按播放。该视频将向您展示开发人员通过左侧轨道上的内容中的步骤 - 以及滚动，视频将向该教程的该部分提前前进。

因为SSH是文档的一点白鲸（它是Docs.Github.com的最受欢迎的文章页面），我决定更多地探索有关什么将使SSH文章更加友好，但这些布局选项为任何教程工作。这是什么样子：

内容站点的搜索和导航通常是相同的，但UX由Intent驱动。

让我们从导航开始。为了在GitHub文档页面上了解内容的广度，我们将事物组织成类别。但是，当用户考虑太多的选择时，会出现类别膨胀。这是'汤过道康宁，'当你有100多种选择时，你会选择哪种汤？选择变得如此压倒客户最终放弃。为了打击类别膨胀，我们策划我们为用户提供的服务（我们可以依靠搜索功能来允许读者使用更多精度导航）。当我们积极纠正我们的内容的精度和准确性。这有助于让我们的用户更快地播放到正确的地方，并使我们作为策展人思考读者正在尝试的事情 - 我们可以根据意图构建这些类别，而不是内容简洁。

因为导航是该网站的基石，所以我写下了这个草图的一些规则：

导航层次结构与内容层次结构合作。产品是顶级，类别是基于意图的策划，主题组织在一个类别中的文章和文章在一个主题中教授概念。上面所看到的是导航在潜入产品区域时如何波动的例子。由于还有一个以上的产品，我们也需要一个看法。

在您正在探索该网站时，使用导航（此Mega菜单）以保持您的面向导向并找到新事物。我从观看开发人员学到的东西使用docs.github.com以及使用数据，是人们通常在一个产品区域内 - 他们在同一课程中经常探索产品。但是，如果你想，我们需要让那种行为容易，因为Docs导航是人们发现新的Github产品的一部分！

现在在搜索。搜索是一种以更精度导航的方式（而不是浏览）。你有一个想法你正在寻找的东西，你想搜索答案。例如，如果您喜欢我，请经常忘记GitHub SSH的工作原理，因此每当您需要使用它时，您都会搜索SSH文章。搜索也是整个网站体验的基石，所以它应该是前沿和中心。

探索这些草图的整个动机是建立一个符合他们所在开发人员的DOC体验。 docs.github.com可以做好组织内容，为您提供访问它的新方法，并自定义为您设计的阅读体验。开发人员文档是产品的一部分，应用程序的扩展名以及代码的一部分。没有它，人们可能会丢失，所以给出航路点很重要，这就是这个系统旨在提供的东西。越魔力“aha！”和“它的工作！”我们可以通过文档激发灵感的时刻，我们越是解锁人们为人们创造性，富有成效的路径，并回到编码业务。

如果您认为文档网站不需要优先考虑或者我们不应该投资它们，请询问开发人员他们需要的内容，然后再次思考您可能在不存在的情况下DOCS的沉浸式，互动和吸引力的经验。而不是刚刚制作另一个文档网站（yads），让我们制作站立的经历 - 我们的开发人员应该得到它。