企业文档管理_为什么这么多企业文档如此糟糕？

企业文档管理

I spend a very large portion of my professional workday reading through technology documentation. Perhaps “reading through” isn’t quite the right way to describe it. At this point, it’s more like quickly scanning menus, FAQs, and paragraph headings for clues to where I can find the exact piece of information I’m after.

我花了很大一部分专业工作时间阅读技术文档。 也许“通读”并不是描述它的正确方法。 在这一点上，它更像是快速扫描菜单，常见问题解答和段落标题，以获取我可以在其中找到确切信息的线索。

With some exceptions, this tends to be the case whether I’m just looking for a quick confirmation of the right command line syntax or whether I’m trying to get my mind around a whole new technology.

除了某些例外情况，无论是我只是想快速确认正确的命令行语法，还是想让自己了解一种全新技术，这种情况都很常见。

基于Web的技术文档：性能不佳的艺术 (Web-based Technology Documentation: The art of underperformance)

Now, I have no complaints with the people who provide detailed syntax guides and main pages — why should they reformat their entire document to highlight some obscure detail for which I may someday come searching?

现在，我对提供详细语法指南和主页的人员没有任何抱怨-他们为什么要重新格式化整个文档以突出显示某些模糊的细节， 有一天我可能会去寻找这些细节？

But when I’m trying to introduce myself to a complicated software package — to figure out its purpose and primary use-case — then it’s reasonable for me to expect a relatively predictable and comfortable route to my goal. Instead, I often encounter a project home page with links to multiple targets with names like “Getting Started,” “How to use…?” “Documentation” and, buried deeply under a few menu layers, “Quick Start Guide.”

但是，当我试图向自己介绍一个复杂的软件包时-要弄清其目的和主要用例-那么我有理由期望有一个相对可预测且舒适的实现目标的途径。 取而代之的是，我经常遇到一个项目主页，该主页具有指向多个目标的链接，这些链接的名称为“入门”，“如何使用...？”。 “文档”，并深深地埋在几个菜单层下的“快速入门指南”。

Often, the pages I’m sent to will be incomplete, apparently the victims of changed minds and budget overruns. Others will cover outdated versions of the software that might easily have a feature set that’s significantly different than the latest version. Worse: the features might actually still exist but, between then and now, they’ve changed names and even icons.

通常，我发送到的页面不完整，显然是改变主意和预算超支的受害者。 其他人将介绍该软件的过时版本，这些版本可能会轻易具有与最新版本明显不同的功能集。 更糟糕的是：这些功能实际上可能仍然存在，但是从那时到现在，它们已经更改了名称甚至图标。

Even if we ignore the quality of the writing — something that can be remarkably difficult and costly to control — and the intelligibility of individual documents, there often seem to be significant version control and project management problems.

即使我们忽略了写作的质量(控制起来可能非常困难且成本高昂)和单个文档的可理解性，通常似乎也存在重大的版本控制和项目管理问题。

I can usually guess what happened: some customers complained that they couldn’t figure out how to use the software, so management — unable to properly assess the current state of the documentation on their own — ordered the creation of a complete new set from scratch. The project starts, but about half way through, the key contributor either leaves the company or is distracted by other deadlines and demands.

我通常可以猜测发生了什么：有些客户抱怨说他们无法弄清楚如何使用该软件，因此管理层(无法自行正确评估文档的当前状态)下令从头开始创建一套完整的新软件。 。 该项目开始了，但是大约一半的时间里，主要贡献者要么离开了公司，要么因其他截止日期和需求而分心。

And there it sits until a few more customers complain that they, too, can’t figure out how to use the software. Rinse. Repeat.

直到有更多的客户抱怨他们也无法弄清楚如何使用该软件，才坐下来。 冲洗。 重复。

Is poor documentation always evil? Absolutely not. I’m often amazed at just how much some open source projects manage to accomplish considering the limited resources they’re usually working with. And, in any case, as long as people (like me) aren’t volunteering to help out, we have no right to grumble.

糟糕的文件记录总是邪恶的吗？ 绝对不。 考虑到开放源代码项目通常使用的有限资源，我经常为它们完成多少任务感到惊讶。 而且，无论如何，只要像我这样的人不自愿提供帮助，我们就无权抱怨。

Is all documentation evil? Nope. While you could argue that there’s way too much of it, Amazon’s AWS maintains a magnificent documentation resource that’s well-written, well-designed, and so well organized across the system that finding elements within any given page is predictable and fast. AWS isn’t the only success story out there, but it’s not exactly part of an overcrowded field, either.

所有文件都是邪恶的吗？ 不。 尽管您可能会说有太多的说法，但Amazon的AWS维护着庞大的文档资源 ，该文档资源写得好，设计合理且在整个系统中井井有条，因此在任何给定页面内查找元素都是可预测且快速的。 AWS并不是唯一的成功案例，但也不完全是人满为患的领域。

技术书籍：性能过高的艺术 (Technology Books: the art of overperformance)

At the other end of the documentation continuum lie books. Remember those? While I may not have purchased a tech book for years, many thousands of other people do it all the time. In fact, at least in the short term, the technology publishing industry seems remarkably healthy.

在文档连续性的另一端是书籍。 还记得那些吗？ 尽管我可能已经多年没有购买技术书籍，但无数人一直在这样做。 实际上，至少在短期内，技术出版业看起来非常健康。

The better traditional publishers will subject a book proposal to very close analysis before concluding that the idea makes sense and that there are enough readers interested to make it worthwhile. Once the writing begins, they’ll throw layers and layers of editors and reviewers at every stage of a book’s production. And when they’ve run out of editors, they’ll stage an editorial board review to make sure it wasn’t all a terrible mistake.

更好的传统出版商将对书的建议书进行非常仔细的分析，然后再得出结论，这个想法是有道理的，并且有足够的读者感兴趣以使其有价值。 一旦开始写作，他们将在书籍制作的每个阶段投入层层的编辑和审阅者。 并且当他们用完所有编辑器时，他们将进行编辑委员会审查，以确保这不是一个可怕的错误。

With some variation, that’s how the editors at Wiley/Sybex and Manning got their job done while working on my books. And it’s also quite similar to the process I go through producing my video courses with the Pluralsight team.

有所变化，这就是Wiley / Sybex和Manning的编辑在撰写书本时完成工作的方式。 这也与我与Pluralsight团队制作视频课程的过程非常相似。

When it’s done properly, the system creates checkpoints at the theme, style, chapter, and even paragraph levels, asking whether this element is needed, is presented as well as it can be, and will fit properly into the greater vision. These checkpoints make for great books, but they tend to be very expensive.

正确完成后，系统会在主题，样式，章节甚至段落级别创建检查点，询问是否需要，是否已显示此元素，并将其适当地放入更大的视野中。 这些检查点造就了不错的书，但它们往往非常昂贵。

Is it overdone? Sometimes. Is the full-blown multi-level editorial system going to be affordable for web-based documentation projects? Perhaps not always.

过度吗？ 有时。 对于基于Web的文档项目，成熟的多层编辑系统是否可以负担得起？ 也许并非总是如此。

But creating high-quality, readable, and well-organized documentation is a significant business need for many companies, so it would probably be a really good idea for them to at least submit what they’ve already got to a thorough audit by someone with experience, technical knowledge, and — most important of all — objectivity. The odds are, that will lead to a far more useful documentation product. And yes: documentation is also a product.

但是，对于许多公司而言，创建高质量，易读且组织良好的文档是一项重要的业务需求，因此对于他们来说，至少将他们已经得到的内容提交给具有以下知识的人员进行彻底审核可能是一个非常好的主意：经验，技术知识，以及最重要的是客观性。 很有可能会导致使用更多有用的文档产品。 是的：文档也是产品。

David Clinton parks a lot of his goods at Bootstrap-IT.com. You might be surprised what you find there…

大卫·克林顿(David Clinton)将许多商品 停放 在 Bootstrap-IT.com上 。 您可能会惊讶于那里的发现……

翻译自: https://www.freecodecamp.org/news/why-enterprise-documentation-awful/

企业文档管理