为什么你公司的文档很糟糕

有关他们讨厌编写和维护文档的软件工程师有一个共同的轨迹。从我所努力的所有公司的浅视看法，这种刻板印象似乎持有。每家公司都有绝对垃圾文档：它没有存在，它有点差，它完全过时，和/或它写得非常糟糕。

然而，我与之合作的工程师从来没有过上过;所有这些都会竭尽全力编写长时间的懈怠评论或电子邮件甚至是ad-hoc文件，以解释概念或项目。这些都是一切形式的文件，非常有用，但是短暂的，并及时丢失（或以凌乱的方式联系）。

有趣的是，当经理进来时试图强迫每个人使用＆＃34;正确的＆＃34;文档工具，文档会变得更糟！而不是使用ad-hoc方法，这导致你喊道，人们刚刚停止 - 他们在使用＆＃34;正确的＆＃34;文档工具。好吧，他们做了一段时间，但不可避免地是＆＃34;适当的＆＃34;文档刚刚腐烂，最终没有人使用它。我最喜欢的行为是与公共休闲频道中的文档相关联的工程师，然后立即在私人通信中追随解释文档是可怕的并且提供了短手解释（私人方法，但私有）。

在Ad-hoc文件上花费的时间和精力显示软件工程师Don＆＃39; t讨厌写作文件。我们都知道它节省了时间和精力，并有助于使我们的同事更加自主。那么为什么地狱是一个始终如一的文档，为什么工程师在ad-hoc文件上花费更多的努力，而不是使用公司指定的正确文档工具？

问题是，这么多公司已经标准化的文档工具是绝对垃圾，用于实际编写文件。它是不是因为他们是越野车，慢，和/或ux灾害（Confluence I＆＃39;看着你）。该问题是这些文档工具尝试组织信息的方式。我称之为树方法与图形方法相比。

组织信息的显而易见的方法是用树。例如，请查看文件系统的工作方式。我们有一个文件层次结构，在这个系统中组织了所有内容。要查找一些x信息，我们可以简单地从顶部开始行驶，选择该分支，这对我们正在寻找的东西最有意义。例如，公司的一组项目的文档可能如下所示：

项目| - 项目A | | - 架构概述| | - 设置指南| ` - ... || - 项目B | | - 架构概述| | - 设置指南| ` - ... |` - 项目c | - ...

作为软件工程师，我们知道像这样的平衡树具有O的查找时间（log（n））。这似乎很棒：由于我们的集体知识增长了找到它的任何特定部分的努力，所以对那种知识的大小是对数的，这意味着我们应该能够在短短时寻找我们的＆＃39;重新寻找什么时间。这是真的，适​​用于一个完美有组织的知识。

问题是我们有一段知识，我们想要记录到Project A和Project B的Project A和Project B - 它在这个层次结构中都在哪里？我们是否将信息复制到两个部分？我们是否完全创建了一个新部分，只是为了处理这些边缘案件的记录？我们只是把它放在项目A和某种方式链接到项目B＆＃39;文件中的某个地方？或者我们只是把它放在项目a中，因为它稍微相关，只是忽略项目b？每个人都试图增加集体知识必须通过这个思想过程，他们不会做出同样的决定。这是文档腐烂，它使得您并不确立某些信息，如果它不完全适合层次结构。

回顾我们的知识查找时间，很明显，如果我们实际在每个分支机构做出正确的决定，那么它就是o（log（n））。但如果我们的信息组织不佳，我们不对分支机构做出正确的决定，我们现在正在回溯领土。与计算机不同，人类在回溯时真的很糟糕，因为我们认为＆＃34;嗯，也许我刚刚错过了它，当我下来分支x。＆＃34;这导致令人沮丧，这导致烦恼，它导致工程师在文档中失去信任。如果他们不相信他们赢得的文件，他们使用它，如果他们不使用它，他们会使用它。

让我们考虑两个最广泛尊敬的文档系统：维基百科和拱门Linux Wiki。任何使用的人都知道他们只是令人难以置信的。在管理信息和集体知识方面，我不知道任何比Wikipedia或Arch Linux Wiki更好的东西。这在很大程度上是由于这些知识体系的伟大工作（巨大感谢这些人），但我争论也是因为他们以不同的方式从严格的层次结构上以不同的方式组织他们的信息。

两者都采取了组织数据的图形方法。每个文档都基本上是自由的，而不是组织一切的层次结构。而不是文档生活确定它与之相关的其他文档，而是使用文档之间的链接来创建该关系。查看随机维基百科页面，看看有多少链接与其他页面有关。通过页面之间的链接创建的这种密集的网络是使这些文档系统的最佳状态。

让我们考虑任何给定信息的查找时间。这是一个棘手的棘手，因为它取决于链接的密度。事实上，我认为我们认为我们可以确定算法运行时，而无需指定一些其他参数。它肯定小于O（n），并且可能近似O（log（n）），但它实际上并不重要。重要的是最糟糕的案例查找时间。

如果我们到达错误的页面，而不是必须潜在地回溯到root，我们只能在我们的页面上进行随机漫步。在最微小的组织系统中，这仍应导致我们所需的信息，因为页面将链接到其他相关的页面。

更重要的是，可以刚刚添加新的信息，并且没有关于将该信息放在哪里需要做出的决定。如果一条信息与项目A和Project B相关，我们只需将其添加为项目A和项目B的新文档和链接。这是现在是自然过程，并且有机缩放。当然，需要一些关心来防止这种情况变得完全乱七八糟，但它是特别困难，对此有一些指导。

它应该毫不奇怪，上面描述的ad-hoc文件方法是有效的图形方法。人员链接的独立文件（而不是在文件中）。然而，我已经看到公司使用工具，而不是倾向于这种自然的做法方式。

我曾经工作过的每家公司都使用了一种基于树的方法来组织文件，并且他们一直非常可怕。其中两个最受欢迎，最大的文档来源，维基百科和Arch Linux Wiki，都使用基于图形的文档方法，并且广泛喜欢和易于使用。一组已支付员工，其工作部分是为了使本文件保持最新，而另一个团队已充满志愿者。如果这不是足够的争论对媒体的沟渠，那么坦率地说，我不知道是什么。

当然，这并不意味着您不应该为您的文档提供其他指南。基于图形的系统无法解决所有问题。例如，4种类型的文档对于记住和使用非常重要。无论它是层次结构还是图形，它都会始终是一团糟。

停止使用基于层次结构的文档。它并不规模，它需要更多的努力，它只是持有你的组织。

请开始使用基于图形的文档系统。它轻松和工程师将自然贡献。