IT 技术作者是否使用了标准/约定？

Question

特尔：博士？很好……在这里：

除了雇用或外包给技术作家之外，是否有技术作家在其行业中采用的基本标准/惯例/实践可以从中学习，以便创建适当的 IT 文档并随着时间的推移维护该文档？

---

在为我们的员工为内部 IT 使用和外部使用编写各种文档时，很明显我们的员工在文档方面都有自己的风格。

从我们的质量文档和受控文档中提取，IT 已经使用了各种 SOP、WI 模板和用于 IT 质量文档的各种表格。这些文档虽然对 IT 内的日常运营不一定有用，但确实可以帮助员工和公司解决 IT 人力资源问题、合规性等问题，并且通常编写得很好、定义明确，并且至少遵循质量部门的模板和文档标准（如版本控制、ECN 等）

但是我们实际的 IT 文档编写仍然缺乏真正的约定/标准。 有些人会使用像 ScreenSteps 这样的 3rd 方工具，其他人只是使用 Word 并创建一个简单的大纲，如：

1. 打开 app
2. 点击“开始全球热核战争”
3. ...
4. 利润

内部 IT 文档实际上更糟，基于当时员工或顾问认为足以唤起他们自己的回忆或基于他们选择的编辑器（vi、word、excel、powerpoint、餐巾纸、内部维基）的任何内容。当员工离开或休假时，问题就出现了，甚至要争先恐后地找出基本信息。 有时只有文件日期是数据是否仍然相关的指标。

虽然简单的大纲、实际截图，甚至完整的高清视频都很好，但我们没有真正的 IT 技术作家，不禁认为我们在这方面缺乏。

我们可以为我们的文档制定我们自己的标准以及批准的模板吗？是的，但为什么要重新发明轮子呢？如果技术作家的“公会”中已经存在这样的标准和约定，我们最好遵循这些约定，以便我们的文档清晰、简洁和专业。

为了避免被告知“ Google It ”，我确实查看了一些显示一些格式设置实践的网站，虽然这个 SF Q：IT 文档平台有助于寻找平台和软件来处理写作，但它没有讨论内部是否真的有标准行业。

那么，除了聘请或外包给技术作家之外，是否有技术作家在他们的行业中采用的基本标准/惯例/实践可以从中学习，以便创建适当的 IT 文档并随着时间的推移维护该文档？

Answer 1

写作是一门学科。

我已经完成了很多工作，而且我已经掌握了一个未受过培训的人在没有文档作为我工作的重中之重的情况下所能获得的基础知识。时间已经向我展示了我制作的哪些文档会被实际阅读，以及 Eternal TL; DR 的书架上会有哪些内容。这实际上是编写任何东西的第一条规则：

了解你的听众。

内部 IT 文档的受众是我们自己。还有系统管理员？当我们获取文档，尤其是内部文档时，我们正在寻找：

• 可定位
• 简短的
• 说到点子上了
• 带我去我要去的地方

关于系统背景的五段解释将被忽略，以支持它下面的清单，因为我们很匆忙，我们只需要完成它。如果那里的警告是，如果您不按顺序执行某些步骤，它将删除您所有的备份是在跳过的文本块中，也许它应该有一些引起注意的格式，或者可能在清单也是。

流程文件

这种类型的文档都是关于描述做某事的方式。对于未经培训的人来说，这是最容易制作的，因为大多数情况下它只是写下一系列要遵循的步骤。根据我的经验，好的流程文档具有以下特点：

• 包含一个检查表。
• 检查清单与运行检查清单的时间和原因的简短摘要位于同一页面上。
• 在清单下方或链接页面上，是一份较长的文档，描述了清单背后的理论和可能遇到的变化。

您想要它，以便有要遵循的检查表，并且如果需要，至少页面上已经存在第一级故障排除步骤（或单击一下）。

如果您曾经看过 Microsoft KB 文章，那么这是一种熟悉的格式：摘要、修复、详细信息、受影响的系统。这是有原因的。

故障排除指南

这比流程文档更棘手，因为您必须将决策树编码到文档中。一个简单的清单可能不够，但一个分支清单，一个使用其他清单的链接，是非常可行的。与流程文档相同的规则适用于此类文档：

• 简明扼要，不要在细节中淹没你的读者。
• 明确决策点是什么以及后续行动的去向。
• 保存建筑文档的深入技术背景。

故障排除指南可以是一个大的“选择你自己的冒险”故事，也可以是一个大的项目符号列表，列出系统出现的所有问题及其修复方法。

架构文档

最难生产的单一类型，因为它被设计为参考材料，只有新人希望将他们的头脑围绕在他们刚刚走进的这个复杂事物上，才会被新人引用。

架构文档是原因文档。这就是为什么要使用这个系统而不是那个系统的原因，它们是如何与另一个系统连接的，以及是什么使该连接以它的方式工作。这是您应该在知道生产配置的外观后立即编写的文档，并在进行更改时进行更新。

格式明智，我必须听从专家的意见。

好的文档也不仅仅是它们的模板和格式，统一的外观是好的，确实提高了可读性，它还需要一些其他的东西。

定期更新

养成查看您已经拥有的文档的习惯，以确保它仍然是好的。1.17 版的清单可能不适用于 1.26 版，是时候更新了。死记硬背的清单需要最频繁的更新，因为即使是最小的 UI 更改也可能会破坏整个事情。

每周花10 分钟来查看文档并确定需要清理的东西，可以做一些了不起的事情。

架构文档需要由了解系统的人定期审查。正如我所提到的，这些文件很少使用，但在您确实需要它们时非常有用。您不需要描述 3 年前迁移到 Windows 时校园打印服务集群如何与 NetWare 连接在一起的文档。

可发现的

这是最难得到正确的，因为它依赖于非常大的一部分，在那里你存储你的文件。

我们会告诉任何带着问题来 ServerFault 的人什么？

你已经尝试过什么？

紧随其后

Google 上的热门搜索解决了您的问题。也许你应该尝试一下。

我们搜索我们的文档，我们不去书架。文档存储库需要与 Google 一样可搜索，否则我们将转而使用 Google。

Central Napkin Repository 是一个不适合放置文档的地方，至少如果它没有在线索引（并且不会）。一个简单的 wiki 更好，因为它们中的大多数至少包括基本的文本搜索。一个更好的系统是允许搜索除全文之外的标签以更好地将搜索集中到目标区域的系统。

如果您正在使用支持标签的文档存储库，请将您的标签标准化。有时只需查看 ServerFault 标记列表即可了解原因。用户不应该为了找到他们正在寻找的东西而必须记住vmware的八种排列。这将需要偶尔重新标记工作。