AskOverflow.Dev

AskOverflow.Dev Logo AskOverflow.Dev Logo

AskOverflow.Dev Navigation

  • 主页
  • 系统&网络
  • Ubuntu
  • Unix
  • DBA
  • Computer
  • Coding
  • LangChain

Mobile menu

Close
  • 主页
  • 系统&网络
    • 最新
    • 热门
    • 标签
  • Ubuntu
    • 最新
    • 热门
    • 标签
  • Unix
    • 最新
    • 标签
  • DBA
    • 最新
    • 标签
  • Computer
    • 最新
    • 标签
  • Coding
    • 最新
    • 标签
主页 / server / 问题 / 536650
Accepted
TheCleaner
TheCleaner
Asked: 2013-09-06 06:36:24 +0800 CST2013-09-06 06:36:24 +0800 CST 2013-09-06 06:36:24 +0800 CST

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

  • 772

TL:博士?好吧……这里:

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


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

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

但是我们实际的 IT 文档写作仍然缺乏真正的约定/标准。 有些人会使用 ScreenSteps 之类的 3rd 方工具,而其他人则只需使用 Word 并创建一个简单的大纲,例如:

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

内部 IT 文档实际上更糟糕,基于员工或顾问当时认为足以记录他们自己的记忆或基于他们选择的编辑器(vi、word、excel、powerpoint、餐巾纸、内部 wiki)的任何内容。当员工离开或休假时,问题就出现了,甚至连基本信息都被弄得乱七八糟。 有时只有文件日期是数据是否仍然相关的指标。

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

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

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

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

documentation
  • 1 1 个回答
  • 2004 Views

1 个回答

  • Voted
  1. Best Answer
    sysadmin1138
    2013-09-10T13:22:52+08:002013-09-10T13:22:52+08:00

    写作是一门学科。

    我已经做了很多,而且我已经掌握了一个未经培训的人可以得到的尽可能多的基础知识,而文档不是我工作的首要部分。时间向我展示了我制作的文档实际上会被阅读,以及永恒 TL;DR 的书架上会发生什么。这实际上是写任何东西的第一条规则:

    了解你的听众。

    内部 IT 文档的受众是我们自己。和系统管理员?当我们获取文档,尤其是内部文档时,我们正在寻找:

    • 可定位
    • 简短的
    • 切中要害
    • 带我到我要去的地方

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

    过程文档

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

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

    您想要它,以便有要遵循的清单,并且如果需要,至少页面上已经存在第一级故障排除步骤(或单击即可)。

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

    故障排除指南

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

    • 简明扼要,不要把你的读者淹没在细节中。
    • 清楚决策点是什么以及后续行动的去向。
    • 保存架构文档的深入技术背景资料。

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

    架构文档

    最难制作的单一类型,因为它被设计为参考材料,只会被那些想要了解他们刚刚走进的这个复杂事物的新人所参考。

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

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


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

    定期更新

    养成阅读你已经拥有的文档的习惯,以确保它仍然是好的。1.17 版的清单可能不适用于 1.26 版,是时候更新了。死记硬背的清单需要最多的更新,因为即使是最小的 UI 更改也可能使整个事情变得混乱。

    每周花 10 分钟来查看文档并确定需要清理的内容可以做出令人惊奇的事情。

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

    可发现的

    这是最难做到的,因为它在很大程度上取决于您存储文档的位置。

    我们告诉任何通过 ServerFault 提出问题的人是什么?

    你已经尝试过什么?

    紧随其后的是

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

    我们搜索我们的文档,我们不去书架。文档存储库需要像 Google 一样可搜索,否则我们将直接使用 Google。

    Central Napkin Repository 是存放文档的好地方,至少在它没有在线索引的情况下(而且它不会)。一个简单的 wiki 更好,因为它们中的大多数至少包括基本的文本搜索。更好的系统是除了全文之外还允许搜索标签以更好地将搜索集中在目标区域上的系统。

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

    • 12

相关问题

  • 如何交付 IT 工具的文档?

  • 在活动目录服务器中记录什么是重要的?

  • 教程/培训创建工具[关闭]

  • 您如何记录您的工作、流程和环境?

  • 您希望开发人员向您提供什么级别的文档?

Sidebar

Stats

  • 问题 205573
  • 回答 270741
  • 最佳答案 135370
  • 用户 68524
  • 热门
  • 回答
  • Marko Smith

    新安装后 postgres 的默认超级用户用户名/密码是什么?

    • 5 个回答
  • Marko Smith

    SFTP 使用什么端口?

    • 6 个回答
  • Marko Smith

    命令行列出 Windows Active Directory 组中的用户?

    • 9 个回答
  • Marko Smith

    什么是 Pem 文件,它与其他 OpenSSL 生成的密钥文件格式有何不同?

    • 3 个回答
  • Marko Smith

    如何确定bash变量是否为空?

    • 15 个回答
  • Martin Hope
    Tom Feiner 如何按大小对 du -h 输出进行排序 2009-02-26 05:42:42 +0800 CST
  • Martin Hope
    Noah Goodrich 什么是 Pem 文件,它与其他 OpenSSL 生成的密钥文件格式有何不同? 2009-05-19 18:24:42 +0800 CST
  • Martin Hope
    Brent 如何确定bash变量是否为空? 2009-05-13 09:54:48 +0800 CST
  • Martin Hope
    cletus 您如何找到在 Windows 中打开文件的进程? 2009-05-01 16:47:16 +0800 CST

热门标签

linux nginx windows networking ubuntu domain-name-system amazon-web-services active-directory apache-2.4 ssh

Explore

  • 主页
  • 问题
    • 最新
    • 热门
  • 标签
  • 帮助

Footer

AskOverflow.Dev

关于我们

  • 关于我们
  • 联系我们

Legal Stuff

  • Privacy Policy

Language

  • Pt
  • Server
  • Unix

© 2023 AskOverflow.DEV All Rights Reserve