Using Diagrams in IT Documentation: Best Practices

在IT文档中使用图表:最佳实践

2021-02-10 19:00 clickhelp

本文共1316个字,阅读需14分钟

阅读模式 切换至中文

What is IT documentation? In a nutshell, it is a full database of all the information an IT team needs to fulfill its tasks efficiently. It should involve all kinds of key documents: detailed instructions for specific operations, onboarding docs, information about customers, standard operating procedures (SOPs), and many other things. Informative IT documentation must cover a lot of spheres: from recovery plans and instructions to hardware and software. IT documentation's main goal is to increase the efficiency of work: documentation helps to speed up common processes and make them flawless - here appears the capacity to develop your business in general. Benefits of IT Documentation If you still ask yourself whether you need IT documentation in your company, here are the benefits of it: Eliminate errors and save time. Even repetitive processes sometimes make experienced employees stumble and blunder or spend another 10-15 minutes going through the motions. But if they use informative instructions, they will make fewer mistakes and spare time. Great help desk support. Help desk support specialists provide assistance in issues related to hardware and software, computer systems, etc. IT documentation regulates this field as well. It tells how to solve a problem. And, special service databases can be created. Can you imagine a situation when a user is transferred from one technician to another, and every time they have to repeat the same details. The best solution is to create a service database, and the first technician can fill in all the necessary information to make it available to all colleagues. This is IT documentation as well. Protect your company. Every company has some specific information that should remain within the company even if employees leave it or go on a long vacation. Critical information should not be only in their heads. IT documentation solves that problem - when all the information has been documented, you won’t lose it even if the employees come and go. Quick and effective onboarding. IT onboarding is one of the processes that should definitely be documented. Strong onboarding documentation can help technicians train themselves and spend less time consulting with more experienced colleagues. IT onboarding templates are quite useful as they show which technology stacks new employees need. Some companies even use IT onboarding checklists. Quick problem-solving. Infrastructure components interaction diagram helps Ops Team reduce time for solving problems (servers, hosting centers, data and command flows, etc). How to Improve IT Documentation? The main question about any type of documentation is whether it has real value. To make your IT documentation valuable, here are the best practices to improve its quality: Figure out what information to document. Documenting is vital, but you cannot document every step you and your teammates make. Some members of your team need hardware and software application inventories and service histories; others need docs on employee onboarding or taking a support call. Make sure that the information you document is in demand. Create standards of documenting information. Using templates can become one of the steps towards standardization of documentation, thus helping to manage the information easily - to navigate and read it. Determine who should document. Sometimes, it is hard to find a person who can document. Should it be a person who at the moment has time to document? Not exactly. It should be a person who at first-hand deals with the task. This person has more information than anyone else. Make sure the information is relevant. You should update existing documents when something changes. It is better to choose the date of review for every significant document beforehand. In this case, you will not forget to update docs and surely will include all the changes - sometimes, teams simply forget to update docs thinking that it has already been done. And, you will define the scope of documents that are to be replenished - it is not always obvious if this or that document should be updated or not. Try out your documentation. To check if your IT documentation is easy-to-understand and describes the processes correctly, simply try to follow your instructions step by step to see where they lead you. Add visuals. Needless to say, good visuals make the information natural and clear. Of course, you can use videos in your documentation. Our post, Latest Tips on Using Video Content in Technical Documentation, will give you more information about that. But if you are not ready to create videos, you can use diagrams; check out our post Diagrams in Software Documentation. How to Use Diagrams in IT Documentation? Diagrams are an amazing format of information visualization in technical documentation. In the sea of words and data, diagrams give users an understanding of ideas, concepts, relations, statistical data, constructions, and many other things. Today, one may find a great variety of diagram types: Project chart (project timeline, status table, decision tree) Software design diagram (UML model diagram, program flowchart, Jackson diagram) Database diagram (database model diagram, ORM diagram) Business diagram (business matrix, enterprise architecture, target diagram) Mind map (brainstorming diagram, concept map) etc. One of the greatest things today is that diagrams are not simply pictures, they can be dynamic, which attracts the attention of users and clearly transmits the message of the document. And, here are the most popular diagram tools: Miro. Is a collaborative platform for teams. You can create amazing diagrams for complex systems and processes. Easy-to-use and offers a great variety of templates. Creately. Is a simple diagramming tool that allows real-time collaboration. All types of diagrams are available, from flowcharts to advanced infographics. MyDraw. Is an advanced diagramming software that has powerful features for any type of diagram you need. Gliffy Diagram. Is an online diagramming software for building, editing, and sharing. Suitable for companies of any size. Moqups. Is a visual collaboration tool that allows you to create a wide range of visuals for any project: mockups, diagrams, prototypes, dashboards, and so on. Dia. On-premise drawing tool for diagrams, electronic designs, site building, etc. Is great for engineers. GoJS. Diagram creating tool to make flow charts, genograms, and more. Suitable for businesses of all sizes. Of course, there are many more alternatives. You need to check carefully all the features to choose what suits you best. For example, it is important to have the option of generating embed code to insert your diagrams in the help authoring tool you use for creating IT documentation. Actually, you can create, insert, and store diagrams as pictures, but that is troublesome: if you use the same picture in several topics or projects, you won't manage to update it quickly everywhere if it changes. That is why we highly recommend you creating diagrams in online systems to use embed code. You insert not a picture but a piece of HTML code that gets data from the diagramming tool and displays the diagram. This mechanism does the following: in case something changes, the diagram gets updated in all topics and projects. In ClickHelp, you can create IT documentation online and insert diagrams into your online documentation - we support all the diagram tools that allow users to work with embed code. Here are the most popular ones: Draw.io Lucidchart Gliffy And here is a more detailed instruction for you to read more on the topic. Conclusion Using diagrams in IT documentation is an awesome solution to make information clear and concise. Some experts even call them “visual aid” as they are suitable for all kinds of users, even those who suffer from dyslexia (check out our post - Technical Documentation for People With Dyslexia). It means that your documentation is more accessible and user-friendly. If you know best practices in this field, you are able to create brilliant documentation, especially with the right tools at hand. Good luck with your technical writing! ClickHelp Team Author, host and deliver documentation across platforms and devices
什么是文档?简单地说,它是一个完整的数据库,包含了it团队高效完成任务所需的所有信息。它应该涉及各种关键文档:具体操作的详细说明,入职文档,关于客户的信息,标准操作程序(SOP),以及许多其他东西。信息性的IT文档必须涵盖很多领域:从恢复计划和说明到硬件和软件。IT文档的主要目标是提高工作效率:文档有助于加快公共流程并使其完美无缺--这似乎是开发您的业务的一般能力。 IT文档的好处 如果您仍然问自己公司是否需要IT文档,下面是IT的好处: 消除错误,节省时间。即使是重复的流程,有时也会让有经验的员工跌跌撞撞犯错,或者再花10-15分钟走过场。但是如果他们使用信息性的指令,他们会犯更少的错误并节省时间。 很好的服务台支持。服务台支持专家在与硬件和软件,计算机系统等有关的问题上提供帮助。IT文档也管理这一领域。它告诉你如何解决问题。并且,可以创建特殊的服务数据库。你能想象这样一种情况吗?当一个用户从一个技术人员转到另一个技术人员时,每次他们都要重复同样的细节。最好的解决方案是创建一个服务数据库,第一个技术人员可以填写所有必要的信息,使其可供所有同事使用。这也是它的文档。 保护你的公司。每家公司都有一些特定的信息,即使员工离开公司或休长假,这些信息也应该保留在公司内部。关键信息不应该只存在于他们的头脑中。IT文档化解决了这个问题--当所有信息都被文档化后,即使员工来来去去,您也不会丢失这些信息。 快速有效的登船。信息技术入职是必须记录的过程之一。强大的入职文档可以帮助技术人员自我培训,并花费更少的时间与更有经验的同事进行咨询。IT入职模板非常有用,因为它们显示了新员工需要哪些技术堆栈。有些公司甚至把它用在登机检查表上。 快速解决问题。基础设施组件交互图帮助Ops团队减少解决问题(服务器,托管中心,数据和命令流等)的时间。 如何改进IT文档? 关于任何类型的文档的主要问题是它是否具有真正的价值。为了使您的IT文档有价值,以下是提高其质量的最佳实践: 弄清楚要记录哪些信息。记录是至关重要的,但是你不能记录你和你的队友所做的每一步。您的团队中的一些成员需要硬件和软件应用程序清单以及服务历史记录;另一些则需要员工入职或接听支持电话的文档。确保您文档的信息是需要的。 创建记录信息的标准。使用模板可以成为文档标准化的步骤之一,从而帮助轻松地管理信息--导航和阅读信息。 确定谁应该记录。有时,很难找到一个能记录文档的人。是否应该是一个目前有时间记录的人?不完全是。他应该是第一手处理这项任务的人。这个人掌握的信息比任何人都多。 确保信息是相关的。当某些内容发生变化时,您应该更新现有文档。最好事先为每一份重要文件选择审查日期。在这种情况下,您不会忘记更新文档,并且肯定会包括所有的更改--有时,团队会忘记更新文档,以为已经完成了。并且,您将定义要补充的文档的范围--这个或那个文档是否应该更新并不总是显而易见的。 尝试您的文档。要检查您的IT文档是否易于理解,是否正确地描述了过程,只需尝试一步一步地遵循您的指示,看看它们将您引向何方。 添加可视化。不用说,良好的视觉效果使信息自然清晰。当然,您可以在文档中使用视频。我们的帖子,关于在技术文档中使用视频内容的最新提示,将会给你更多关于这方面的信息。但如果您还没有准备好创建视频,可以使用图表;查看我们在软件文档中发布的图表。 如何在IT文档中使用图表? 图表是技术文档中一种令人惊叹的信息可视化格式。在文字和数据的海洋中,图表给了用户对思想,概念,关系,统计数据,构造和许多其他东西的理解。 今天,人们可以找到各种各样的图表类型: 项目图表(项目时间表,状态表,决策树) 软件设计图(UML模型图,程序流程图,Jackson图) 数据库图(数据库模型图,ORM图) 业务图(业务矩阵,企业架构,目标图) 思维导图(头脑风暴图,概念图) 等等。 今天最伟大的事情之一是,图表不是简单的图片,它们可以是动态的,这吸引了用户的注意力,并且清晰地传递了文档的信息。 下面是最流行的图表工具: 米罗。是一个团队协作平台。您可以为复杂的系统和过程创建惊人的图表。易于使用并提供多种模板。 克雷特利。是一个允许实时协作的简单图表工具。所有类型的图表都是可用的,从流程图到高级信息图形。 我的画。是一个高级的图表绘制软件,对于任何类型的图表都具有强大的功能。 格利菲图。是一个用于构建,编辑和共享的在线图表绘制软件。适用于任何规模的公司。 莫克斯。是一个可视化协作工具,允许您为任何项目创建广泛的可视化:模型,图表,原型,仪表板等等。 迪亚。内部绘图工具,用于图表,电子设计,网站建设等,是伟大的工程师。 戈伊斯。图表创建工具,用于制作流程图,全貌图等。适用于各种规模的企业。 当然,还有更多的替代方案。您需要仔细检查所有功能,以选择最适合您的功能。例如,具有生成嵌入代码的选项,以便在用于创建it文档的help authoring工具中插入图表是很重要的。 实际上,您可以将图表创建,插入和存储为图片,但这很麻烦:如果您在多个主题或项目中使用相同的图片,如果图片发生变化,您将无法在所有地方快速更新它。这就是为什么我们强烈建议您在在线系统中创建图来使用嵌入代码。您插入的不是图片,而是一段HTML代码,它从图表工具获取数据并显示图表。此机制执行以下操作:如果某些内容发生更改,则会更新所有主题和项目中的关系图。 在ClickHelp中,您可以在线创建IT文档,并在您的在线文档中插入图表-我们支持所有允许用户使用嵌入式代码的图表工具。 下面是最受欢迎的几种: Draw.io LucidChart 格利菲 这里有一个更详细的指导,供你阅读更多关于这个主题的内容。 结论 在IT文档中使用图表是使信息清晰和简洁的一个很棒的解决方案。一些专家甚至称它们为“视觉辅助工具”,因为它们适合各种用户,甚至是那些患有阅读障碍的用户(查看我们针对阅读障碍者的后期技术文档)。这意味着您的文档更容易访问,用户更友好。如果您了解该领域的最佳实践,那么您就能够创建出色的文档,尤其是在手边有合适的工具的情况下。 祝你的技术写作好运! 单击帮助小组 跨平台和设备编写,托管和交付文档

以上中文文本为机器翻译,存在不同程度偏差和错误,请理解并参考英文原文阅读。

阅读原文