How to Write Awesome Internal Documentation?

如何编写出色的内部文档?

2022-05-25 21:00 clickhelp

本文共1408个字,阅读需15分钟

阅读模式 切换至中文

As your business grows, your company knowledge base expands. Documents tend to accumulate on the employees’ PCs, usually connected by intranet. This is an internal document management system allowing for storing and sharing information. The information is generally structured. Every employee can see the structure in the file manager. It is presented in folders usually named Departments, Projects, Teams, Personal folders (each employee has their own folder on the disc), Contracts/Agreements, Quality Assessment, Training, Certification/Licensing, etc. There are also such folders as ‘General’ or just ‘Documents’ used as information silos. Here you can find all kinds of documents not fitting into any other folders. The thing is, no matter how well-structured the information in the file manager looks, people always find it hard to get the info they need. The structure described above is usually too general. Sometimes people are just too lazy to share files in common folders, and the information finally gets lost in personal folders. Sometimes people share files via company e-mail and forget to upload them on the intranet. These are just some of the reasons why internal documentation systems become inefficient. This blog will help you learn the best practices for internal documentation creation. Internal Documentation and Its Types Internal documents can be split into several groups. The main types are listed below. As a rule, the largest group is project documentation. This group includes all project-specific information. If it is a large engineering company, this information consists of design and detailed design documents, drawings, specifications, datasheets, terms of reference, design assignments, technical queries, and other process documentation, contractual and cost-estimate documentation, minutes of meetings, etc. If it is an IT company, internal documentation can include details on which tools to use for development, how to use the build process, which coding practices to choose, etc. Normally, there is a special Projects folder in the company intranet system where the information on all projects developed by the company can be uploaded, accumulated, stored, accessed, and shared. Another type is team documentation (team-relevant information). It usually concerns people involved in a specific project. This information is created, accumulated, and shared taking into account the team’s needs. Usually, there is no general information (like information on completed projects, information on the company’s field of work, etc.). Only the information relevant to the project the team is busy with at the moment is required. Team documentation can include all the docs listed in the previous group but with an intermediate (non-finished) status, which is logical when the work is ‘ongoing.’ After the team finalizes the documents, they can be shared with other employees in the Projects folder. Onboarding documentation. This type of internal document includes your company policies, HR processes, organization structure, top-level employees, etc. Getting acquainted with information of this kind helps new hires to get immersed in the regular work process. Benefits of Internal Documentation If you create and manage documentation the right way, it becomes an asset that can give your business a number of advantages. Some of them are listed below. Generally speaking, it enhances your overall company efficiency. People get more done in less time. If the internal knowledge base of the company is not just information silos but is structured and organized, searching for information will become faster and more convenient. The result will be saved extra time otherwise wasted on clueless searches on the intranet or writing e-mail requests to colleagues to provide the necessary documentation. Speeding up the onboarding process is another advantage. Of course, documentation cannot substitute face-to-face communication with colleagues, but it can facilitate the process of the new hires getting acquainted with the internal work practices. Promoting knowledge-sharing practices within the organization can be also added to this list. If a well-organized, structured, and easily accessible internal documentation system is available, the employees are motivated to share their knowledge. This is what makes state-of-the-art organizations different from backward authoritarian companies where the only stimulus for sharing knowledge is an order from the supervising manager. Best Practices for Creating Internal Documentation When creating internal documents, you should consider several important factors that will help your employees read the information carefully, not ‘look through’ or just skip it as useless or too hard to understand. Make texts concise and simple. This rule of thumb works for any style, genre, document type, or format. No matter what language it is – IT, engineering, or medicine – the main thing is to avoid complex sentences and try not to ‘pack’ all possible information in one sentence. Avoid humor, metaphors, and idioms. These often look ambiguous and are sometimes hard to grasp even for native speakers, to say nothing of the employees or partners who will read the translated version of documents (in case you are an international company). Make information focused and sufficient enough for the employees to solve a problem. Use visuals (graphs, diagrams, drawings, screenshots, figures, images). On the one hand, Illustrations help the reader to perceive the information. On the other hand, any visual is a chance to switch from reading to viewing and have a short rest before plunging into the text again. Make search fast and convenient. This can be achieved if there is a search bar (‘quick find’ bar) where the user can enter an information request. This is especially important for new hires, as they cannot understand the structure of the company or the scope of its work. In the case of a simple search using a search bar, they can just enter the keywords, and the system will offer a list of suggestions. Make navigation easy. As in the previous case, the employees might not understand the whole ‘ramified’ documentation tree. This understanding comes only with experience, and when experience is not profound enough, navigation via cross-links will be very useful. It will help the user to gather all the related information in one place. Internal Documentation With ClickHelp ClickHelp offers a powerful online documentation tool based on single sourcing and content reuse. This allows the use of ready-made content from one project to another without wasting time on checking if text fragments from several projects coincide and derive from the same reference text. Texts based on single sourcing are automatically updated. This makes the authoring process faster and more efficient, especially in the case of multiple authors working on the same project. Besides single sourcing and content reuse, ClickHelp offers cloud content hosting. This saves the company budget otherwise spent on buying a company server. At the document creation stage, ClickHelp offers automatic creation of TOCs (Tables of contents) for your documents with one click of a button. This feature helps to organize each document and make it easy to navigate. Other outstanding features are reviewing and commenting. These are important technical documentation tools that can be used on a daily basis in the routine work process of any design and engineering company where reviewing or revising documents is normal. Several revisions of a text can occur before the document is finalized. With ClickHelp, the user will get notifications about comments or questions from colleagues or reviewers on the dashboard. This allows resolving problems at the initial stage of documentation development. ClickHelp online documentation tool will make the life of your employees easier as it offers a patented full-text search engine based on taxonomies (index keywords) and search customization features. If you have to deal with foreign-language documentation of your partners or translate your own internal docs into other languages, the ClickHelp online documentation tool will make things easier with the Translation Module. In other words, the ClickHelp online documentation tool is a help authoring tool that combines many features and supports the process of document creation and management at all stages of the Document Development Life Cycle (DDLC). The stages include analyzing and planning, design, content development and reviewing, publishing and maintenance. Conclusion Internal documentation can be a valuable asset to your company. However, this can be achieved only in the case of proper documentation creation and management. Only in this case will this asset work, save time, enhance efficiency, and bring profit. ClickHelp offers an easy way to make your business more competitive by improving your company’s internal documentation. Good luck with your technical writing! ClickHelp Team Author, host and deliver documentation across platforms and devices
随着您业务的发展,您公司的知识库也在不断扩展。文档往往会堆积在员工的PC上,这些PC通常通过内部网连接。这是一个内部文档管理系统,允许存储和共享信息。信息通常是结构化的。每个员工都可以在文件管理器中看到该结构。它以文件夹的形式呈现,通常命名为部门、项目、团队、个人文件夹(每个员工在光盘上都有自己的文件夹)、合同/协议、质量评估、培训、认证/许可等。还有一些文件夹,如“常规”或“文档”,用作信息孤岛。在这里,您可以找到不适合放入任何其他文件夹的各种文档。 问题是,无论文件管理器中的信息看起来多么结构化,人们总是发现很难获得他们需要的信息。上面描述的结构通常过于笼统。有时人们只是懒得共享公共文件夹中的文件,而信息最终会在个人文件夹中丢失。有时,人们通过公司电子邮件共享文件,却忘记将它们上载到Intranet上。 这些只是内部文件系统效率低下的部分原因。本博客将帮助您了解创建内部文档的最佳实践。 内部文件及其类型 内部文档可以拆分为多个组。主要类型如下所示。 通常,最大的组是项目文档。该组包括所有项目特定的信息。如果是一家大型工程公司,则此信息包括设计和详细设计文档、图纸、规格、数据表、职权范围、设计任务、技术查询和其他过程文档、合同和成本估算文档、会议纪要等。如果是一家IT公司,则内部文档可以包括有关使用哪些工具进行开发、如何使用构建过程、通常,在公司内部网系统中有一个专门的项目文件夹,在该文件夹中可以上载、累积、存储、访问和共享公司开发的所有项目的信息。 另一种类型是团队文档(团队相关信息)。它通常与参与特定项目的人员有关。这些信息的创建、积累和共享都考虑到了团队的需求。通常,没有一般信息(如已完成项目的信息、公司工作领域的信息等)。只需要与团队目前正在忙于的项目相关的信息。团队文档可以包括前一组中列出的所有文档,但状态为中间(未完成),当工作“正在进行”时,这是合乎逻辑的。在团队最终确定文档后,可以在“项目”文件夹中与其他员工共享这些文档。 入职文档。这类内部文档包括公司政策、HR流程、组织结构、高层员工等。熟悉这类信息有助于新员工融入常规工作流程。 内部文档的优点 如果您以正确的方式创建和管理文档,它将成为一项资产,可以为您的企业带来许多优势。下面列出了其中的一些。 一般来说,它可以提高公司的整体效率。人们可以在更短的时间内完成更多的工作。 如果公司的内部知识库不仅仅是信息孤岛,而是结构化和组织化的,那么搜索信息将变得更快、更方便。 这样做可以节省额外的时间,否则就浪费在对内部网进行毫无头绪的搜索或向同事发送电子邮件请求提供必要的文档上。 加速入职流程是另一个优势。当然,文档不能代替与同事的面对面交流,但它可以促进新员工熟悉内部工作惯例的过程。 在组织内促进知识共享做法也可列入这一清单。如果有一个组织良好、结构合理且易于访问的内部文档系统,员工就会有动力分享他们的知识。这就是先进的组织与落后的专制公司的不同之处,在专制公司中,分享知识的唯一刺激因素是监督管理者的命令。 创建内部文档的最佳做法 在创建内部文档时,您应该考虑几个重要因素,这些因素将帮助您的员工仔细阅读信息,而不是“浏览”或跳过无用或难以理解的信息。 使文本简洁明了。此经验法则适用于任何样式、流派、文档类型或格式。无论是什么语言—-IT、工程或医学——最主要的是避免复杂的句子,尽量不要在一个句子中“包装”所有可能的信息。 避免幽默、隐喻和习语。这些文件通常看起来模棱两可,有时甚至连母语使用者也很难理解,更不用说阅读翻译版文件的员工或合作伙伴了(如果您是一家国际公司)。 使信息足够集中和充分,足以让员工解决问题。 使用视觉效果(图表、示意图、绘图、屏幕截图、数字、图像)。一方面,插图有助于读者感知信息。另一方面,任何视觉都是一个从阅读切换到观看的机会,在再次投入文本之前有一个短暂的休息。 使搜索快速方便。如果有一个搜索栏(“快速查找”栏),用户可以在其中输入信息请求,则可以实现这一点。这对新员工来说尤其重要,因为他们不了解公司的结构或工作范围。在使用搜索栏进行简单搜索的情况下,他们只需输入关键字,系统就会提供一个建议列表。 轻松导航。与前面的情况一样,员工可能不理解整个“分支”文档树。这种理解只有在经验的基础上才能实现,当经验不够深刻时,通过交叉链接进行导航将非常有用。它将帮助用户在一个地方收集所有相关信息。 ClickHelp的内部文档 ClickHelp提供了一个基于单一来源和内容重用的强大在线文档工具。这允许将现成的内容从一个项目使用到另一个项目,而无需浪费时间检查来自多个项目的文本片段是否一致以及是否源自相同的参考文本。基于单一来源的文本将自动更新。这使得创作过程更快、更有效,尤其是在多个创作者处理同一项目的情况下。 除了单一来源和内容重用,ClickHelp还提供云内容托管。这节省了公司购买公司服务器的预算。 在文档创建阶段,ClickHelp提供了通过单击一个按钮为您的文档自动创建TOC(目录)的功能。此功能有助于组织每个文档并使其易于导航。 其他突出的功能是审查和评论。这些都是重要的技术文档工具,可在任何设计和工程公司的日常工作流程中使用,在这些公司中,审查或修订文档是正常的。在文档定稿之前,可能会对文本进行多次修订。使用ClickHelp,用户将在仪表板上收到同事或审阅者的评论或问题通知。这允许在文档开发的初始阶段解决问题。 ClickHelp在线文档工具将使您的员工的工作更加轻松,因为它提供了一个基于分类法(索引关键字)和搜索自定义功能的专利全文搜索引擎。 如果您必须处理合作伙伴的外语文档或将您自己的内部文档翻译成其他语言,ClickHelp在线文档工具将使翻译模块使事情变得更容易。 换句话说,ClickHelp缐上文件工具是一种说明撰写工具,它结合了许多功能,并支援文件开发生命周期(DDLC)所有阶段的文件建立和管理程序。这些阶段包括分析和规划、设计、内容开发和审查、发布和维护。 结语 内部文档是公司的宝贵资产。但是,只有在正确创建和管理文档的情况下,才能实现这一点。只有在这种情况下,这一资产才能发挥作用,节省时间,提高效率,并带来利润。ClickHelp提供了一种简单的方法,通过改进您公司的内部文档,使您的企业更具竞争力。 祝你的技术写作好运! 单击帮助团队 跨平台和设备创作、托管和交付文档

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

阅读原文