许多技术问题最终会变成人的问题,缺乏良好的文档也不例外。编写和维护文档是一种需要鼓励和培养的习惯。不幸的事实是,如果没有文档文化,再多的工具也无济于事。今天,我们将看看 3 家高性能工程公司,Google、Twitter 和 Spotify,如何处理他们的技术文档并建立文档文化。
Riona MacNamara在2016年发表了一篇精彩的,讲述了她在谷歌改善其内部文档状况的工作。我们强烈建议你观看这个演讲(只有30分钟),但这里有一些他们在2014年时面临的问题的有趣亮点。
早在2014年,Twitter有3名技术文档写手。在其他方面,他们的职责是协助1000多名软件工程师编写内部文档。同时,在Twitter,围绕着文档的总体氛围是不完整的、过时的,甚至是不存在的。大多数文档都在Confluence中,但也有一些是在Google Docs或READMEs中。
Simeon Franklin和Marko Gargenta有一个很棒的,他们讨论了他们采取的策略。与谷歌类似,他们开始了改变人们对文档的看法的旅程。
他们提出了软件工程师和测试的例子:不久前,人们还不期望软件工程师写测试。这种期望已经被颠覆了,今天,未经测试的代码是不被看好的。他们想在Twitter的内部对文档做同样的事情。
他们的方法包括三个部分。
为了使文档编写更容易和标准化,他们推出了一个新的文档即代码的堆栈,叫做DocBird,它是一个围绕Sphinx的定制包装。与g3docs类似,它从源头自动构建你的文档。它消除了 "文档在哪里 "的问题。
最后,他们为文档创建了共享模板。这些模板有共同的部分和问题,可以被复制到项目中作为起点使用。盯着一张空白的画布有时是开始写作的最困难的部分。
让Spotify的故事变得有趣的是,他们已经在一个叫做的项目中开源了他们用于文档方法的大部分堆栈。
Backstage是Spotify众多的一个软件目录。它有一长串的功能和插件,但最受欢迎的功能之一是对文档即代码的集成支持。
在内部,我们叫它TechDocs。到目前为止,它是Spotify使用最多的插件--占我们Backstage流量的20%(尽管它只是130多个插件中的一个)。
Spotify使用Backstage的文档即代码的过程就像我们以前的案例研究一样:工程师们认为第三大问题是无法找到他们工作所需的技术文档。文档分散在Confluence、Google Docs和自定义网站上,而且什么都找不到。
Gary Niemen有一个演讲,他讨论了他们团队在建立Spotify的 "文档即代码+"基础设施方面的工作。他强调了一些有趣的经验。
这些故事中有很多共同的主题,但这些经验可以归结为三个要点。
这三家公司也都在工具方面进行了大量的投资。无论你为你的文档堆栈选择什么(我们显然坚信Doctave是一个优秀的解决方案),坚持下去,并确保这是技术文档的唯一地方。关于文档的位置,不应该有任何疑问。
最后,这可能是最难的部分,你需要让文档成为工程文化的一部分。这意味着教开发人员如何写文档,提供使用的例子和模板,组织专门针对文档的黑客日,并与你的组织中具有影响力的工程师合作以设定期望。就像今天测试如何成为大多数工程师接受的规范一样,文档也可以。
笑开网络浅谈10件关于Twitter的有趣事实
你知道吗?Twitter原来并不是这个名字的,本来应该叫做“twttr”的这个著名微博客灵感来源于Flickr。美国的短信短码都是5个字符的,所以一开始Twitter使用10958作为短信短码。后来为了记忆方便改为了40404。
你知道吗?Twitter原来并不是这个名字的,本来应该叫做“twttr”的这个著名微博客灵感来源于Flickr。美国的短信短码都是5个字符的,所以一开始Twitter使用10958作为短信短码。后来为了记忆方便改为了40404。
Twitter服务器的抽风率也是相当著名的。当用户遇到服务器超载的时候,就会看到下面这只“可爱”的超载鲨,这幅图的作者是澳大利亚艺术家兼设计师陆怡颖。她异想天开的画了几只红鸟用网从海洋中用渔网“拯救”鲸鱼。画面还有一行