题 是否有IT技术作者使用的标准/惯例?


TL:DR?精...这里:

如果没有招聘或外包给Tech Writer,是否有技术作家在其交易中使用的基本标准/惯例/惯例,可以从中学习以创建适当的IT文档并随着时间的推移维护该文档?


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

从我们的质量文档和受控文档中提取,IT已经为SOP,WI和用于IT质量文档的各种表单使用了各种模板。这些文档虽然不一定对IT中的日常操作有用,但确实可以帮助员工和公司处理IT人力资源问题,合规性等,并且通常编写得很好,定义良好,并且至少遵循质量部门的模板和文档标准(如版本控制,ECN等)

但是我们的实际IT文档编写仍然缺乏真正的约定/标准。  有些人会使用像ScreenSteps这样的第三方工具,有些人只会使用Word并创建一个简单的轮廓,例如:

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

内部IT文档实际上更糟糕,基于员工或顾问认为当时足以慢慢移动自己的记忆或基于他们选择的编辑(vi,word,excel,powerpoint,餐巾,内部维基)的任何内容。当员工离开或正在休假时,问题就出现了,并且即使是基本信息,也要进行争夺。 有时只有文件日期是数据是否仍然相关的指示。

虽然简单的轮廓,实际的截图,甚至是完整的高清视频都很好,但我们没有真正的IT技术作者,并且不禁认为我们在这方面缺乏。

我们是否可以为我们的文档制定自己的标准以及批准的模板?是的,但为什么重新发明轮子?如果技术作家的“公会”中已存在此类标准和惯例,我们将更好地遵循这些惯例,以便我们的文档清晰,简洁,专业。

为了避免被告知 谷歌一下,我确实看过显示一些格式化做法的网站,而这个SF Q: IT文档平台 有助于寻找平台和软件来处理写作,它没有讨论行业内是否真的有标准。

因此,如果没有雇用或外包给Tech Writer,技术作者在他们的行业中使用的基本标准/惯例/惯例是否可以从中学习,以便创建适当的IT文档并随着时间的推移维护该文档?


7
2017-09-05 14:36




我有一个文档标准:具有基本系统管理员技能但没有相关产品的先验知识的第三方应该能够成功使用文档。 - Michael Hampton♦


答案:


写作是一门学科。

我做了很多而且我有尽可能多的基础知识,因为没有经过培训的人员可以成为我工作的重中之重。时间已经向我展示了我生产的文件实际上会被阅读,以及将在永恒TL的架子上发生什么; DR。这实际上是写任何东西的头号规则:

了解您的受众。

内部IT文档的受众就是我们自己。和系统管理员?当我们找到文档,特别是内部文档时,我们正在寻找:

  • 可定位
  • 简要
  • 到了这一点
  • 让我到我要去的地方

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

流程文档

这种类型的文档都是关于描述某种做法的方式。对于未经训练的人来说,这是最容易生产的,因为大多数情况下只是写下了一系列要遵循的步骤。根据我的经验,良好的流程文档具有以下特征:

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

你想要它,以便有一个要检查的清单,至少应该在页面上(或点击一下)的第一级故障排除步骤。

如果您曾查看过Microsoft知识库文章,那么这是一种熟悉的格式:摘要,修订,详细信息,受影响的系统。这是有原因的。

故障排除指南

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

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

故障排除指南可以是一个很大的选择你自己的冒险故事,或者可以是一个大的项目符号列表,其中列出了系统出错的一切以及修复它的原因。

架构文档

这是一种最难生产的类型,因为它被设计为参考材料,只有新人才能参与其中,他们只是想要围绕这些他们刚刚走进的复杂事物。

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

格式明智,我不得不顺从这一方面的专家。


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

定期更新

养成查看已有文档的习惯,确保它仍然很好。版本1.17的清单可能不适用于版本1.26,更新时间。死记硬背清单需要更新,因为即使最小的UI更改也可以抛弃整个事情。

投入10分钟 一周 翻阅文档并识别需要清理的东西可以做出惊人的事情。

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

发现的

这是最难做到的,因为它在很大程度上取决于 哪里 你正在存储你的文档。

我们告诉任何来自ServerFault的人有什么问题?

你有什么尝试?

紧随其后

谷歌的热门话题解决了你的问题。也许你应该尝试一下。

我们搜索我们的文档,我们不去书架。文档存储库需要与Google一样可搜索,或者我们只需转到Google。

中央餐巾库是文档的一个不好的地方,至少如果它没有在线索引(并且它不会)。一个简单的wiki更好,因为它们中的大多数至少包括基本的文本搜索。更好的系统是允许在全文之外搜索标签以更好地将搜索聚焦到目标区域的系统。

如果您正在使用支持标记的文档存储库, 标准化您的标签。只需查看ServerFault标记列表,就可以了解原因。用户不应该记住八种排列  只是为了找到他们正在寻找的东西。这将需要偶尔的重新努力。


11
2017-09-09 21:22



这是一篇很棒的文章。不一定来自科技作家的观点,但足以澄清“什么”和“如何”,以帮助将事物置于语境中。如果没有其他人惊人地掩盖这一点,赏金就是你的。 - TheCleaner
@TheCleaner技术创作者和技术作家之间的区别在于,技术作家通常认为这是他们就业的主要目标,技术人员认为这很烦人。前者会比后者更多地使用它,所以会费心去做标准化布局和格式化的事情。技术需要让它变得平易近人,并由有线索的人指导。 - sysadmin1138♦
好帖子。至于架构文档:我倾向于将架构文档的结构基于旧的MIL-STD-498标准。在面向软件开发的同时,OCD,SSS和SSDD文档模板对于传达“为什么”和高级“如何”非常有用。我确实倾向于对它们进行相当多的定制,省略了相关性较低的段落。 - Vincent De Baere