Best Tips to Create Valuable Software Documentation

创建实用软件文档的最佳技巧

2020-12-10 16:30 clickhelp

本文共983个字,阅读需10分钟

阅读模式 切换至中文

One of the most common things users say about technical documentation is that it describes the information they already know. This fact reduces the value of the content to the minimum. Now, when thousands of software products and cloud services appear every day, some things and features seem to be common and widely spread. There is no need to describe them. Technical writers should invent new ways and strategies of writing to create educational, troubleshooting, and helpful content. Have you ever thought about whether your user manuals and instructions are helpful? If you did, let’s see how you can get your writing to the next level. Define Users’ Pains Your main chance to create high-quality troubleshooting content is to examine the software product carefully. Play with it. Being a technical writer, you can easily see the features and functions that the majority of other products already have. You can easily omit this information from your user manual. Pay attention to the things that made you stumble. This is what you are to write about. What seems to be a problem for you as a user is going to be a pain for others. Ask your SME as many questions as you need to divide the information into valuable and trivial. Use your common sense. Users will not suffer if you are not going to describe how to press the on/off button. But if you are not going to inform them how to fix minor things, that is going to be a problem. Inspire Users to Make Decisions and Act Nowadays, the content telling simply how to press the buttons is outdated. What users are looking for is support in their decision-making process. They want to understand how the software works to know what buttons to use and in what order. It means that technical documentation needs a more complex approach. From the user’s point of view, there should be enough data to make informed choices but not to rely barely on intuition and experience. Short introductions at the beginning of each topic and section can be used to describe the basic concepts and principles in your docs. That will add sense and logic to the steps and actions described further. Effective documentation actually answers users’ questions. Make sure you’ve collected all the most important ones, and your documentation allows users to find answers to all of them. You can even formulate questions at the beginning of every topic. Besides, the content is supposed to make users get things done. Allow users to test what you are writing about right away. This is a popular task-based documentation approach when users learn by fulfilling meaningful tasks. Some situations require single tasks, others - multi-task procedures. But in both cases, you provide steps and explanations. All the rest should be done by users. It is a great way to understand new information. But what you are to pay attention to here is how useful your tasks are from the user’s point of view. Again, the choice of tasks should be based on the real needs of users. You can do some task analysis. You are to test the product yourself and watch how other users interact with it: what and how they do. If you have no opportunity to research like that, you can ask your support team or sales managers to provide you with the hottest questions from users. Check out the following post to learn how to set up the process and collect feedback First Technical Writer in a Company - Setting up the Process. Clear and Smart Structure The way you organize content means a lot. Not only the content itself should be valuable, but also the way you represent it. Everyone wants to find the answers right here and right now. That is why online user manuals are most popular as they have online navigation elements like so: table of contents (TOC), index keywords, breadcrumbs, see also list, cross-topic links, full-text search, etc. They help users quickly navigate and identify if they are reading the right topic. The following post will give you more information about that - Navigation in User Manuals. Modern help authoring tools make the process of content organization easier. For example, ClickHelp has several reader UI templates. They are not only different in style, but they offer different ways of content organization, they offer different navigation elements. Some templates are great to build a knowledge base or an FAQ, others are better for searching or pay closer attention to the document’s content. There are templates that have a version selector for multi-version documentation. It all depends on your goal. But surely, the ability to use a ready-made template makes the tech writer’s life easier. Topic-based authoring is another vital principle you should take into consideration. Your technical documentation is supposed to solve users’ problems. So, you can organize the information into topics or sections. For example, installation, configuration, upgrade, user management, troubleshooting, etc. Here the logic is quite clear. But sometimes, when the question described is too complex, it is not enough simply to divide the information into sections. In this case, you need to create a multi-level logical structure of sections and topics based on the client’s practical needs, and division into sections will depend on the situation. Conclusion So, to create helpful technical documentation, you need to do the following: Define user pains to address Make your content actionable and task-oriented Invest enough time and effort into structure creation, this is very important Technical writers do not simply create content, they help people use software and services explaining the information to them. Good luck with writing useful, high-quality content for your readers. Good luck with your technical writing! ClickHelp Team Author, host and deliver documentation across platforms and devices
关于技术文档,用户最常说的一点就是它描述的是他们都已经知道的信息。这一事实将技术文档内容的价值降至最低值。现在,当每天都有成千上万的软件产品和云服务出现的时候,有些东西和特性似乎是广为人知,且广为传播的。没有必要去解释它们。技术文档工程师应该创造新的写作方法和策略,以创建教育性的,故障排除和有帮助的内容。 你有没有想过你的用户手册和使用说明是否是有用的?如果你想过,让我们看看如何让你的编写水平更上一层楼。 定义用户痛点 你创建高质量故障排除内容的主要机会是去仔细检查软件产品。运行一下。作为一名技术文档工程师,你可以很容易地看到大多数其他产品已经具备的特性和功能。你会很容易地从用户手册中省略此信息。注意那些绊倒你的事情。这就是你要编写的。当你是一个用户的时候,对你来说似乎是一个问题的事情对其他人来说却是一种痛苦。问你的中小型企业用户问题,越多越好,把信息分成有价值信息和琐碎信息。运用你的常识。如果你不打算描述如何按开/关按钮,用户就不会感到痛苦。但如果你不告诉他们如何解决细节问题,那就会有问题。 激励用户做出决定并采取行动 如今,告诉如何按下按钮的简单内容已经过时了。用户想要的是在他们做决策过程中的支持。他们想要了解软件是如何运作的,想知道使用什么按钮和按什么顺序使用按钮。这意味着他们对技术文档有着更复杂的要求。从用户的角度来看,应该有足够的数据来做出有见地的选择,而不是仅仅依靠直觉和经验。在每个主题和小节开头的简短介绍可以用来描述你的文档中的基本概念和原则。这将为下一步要描述的步骤和行动提升意义和逻辑。有效的文档实际上回答了用户的问题。确保你已经收集了所有重要的问题,并且你的文档能让用户找到所有问题的答案。你甚至可以在每一个主题的开头构思问题。 况且,内容该帮用户解决问题。允许用户立即测试你编写的内容。有一种流行的基于任务的文档方法,就是用户通过完成有意义的任务来学习。有些情况要求单个任务,有些则需要多任务程序。但在这两种情况下,你都提供了步骤和说明。而剩下的应该由用户来完成。这是理解新信息的好方式。但在这里你要注意的是,从用户的角度来看,你的任务有多实用。再次强调,你选择的任务要基于用户的真实需求。你可以做一些任务分析。你可以自己测试产品,并观察其他用户如何与它互动:用户做什么和怎样做。如果你没有机会做这样的研究,你可以让你的支持团队或销售经理为你提供用户问得最多的问题。查看下面的帖子,了解如何设置流程和收集反馈。一家公司里第一个技术文档工程师——设置流程。 清晰智能的结构 你组织内容的方式意义非凡。不仅内容本身要实用,你呈现它的方式也要有价值。每个人都想在当下立刻找到答案。这就是为什么在线用户手册最受欢迎的原因,因为它们具有在线的导航元素,比如:目录(TOC),索引关键字,面包屑式导航,参照列表,跨主题链接,搜索全文等。这些能帮助用户快速导航并识别他们是否正在阅读正确的主题。下面的帖子将给你更多关于上述方面的信息——用户手册中的导航。 现代的帮助创作工具使内容组织过程变得更容易。例如,ClickHelp(单击帮助)有几个阅读器界面设计模板。它们不仅风格不同,也提供了不同方式来组织内容,而且提供不同的导航元素。有些模板很适合于构建知识库或FAQ(检索系统),而其他模板则更适合于搜索或对文档内容更密切地关注。有些模板带有用于多版本文档的版本选择器。这完全取决于你的目的。可以肯定的是,有能力使用现成的模板会让技术文档工程师的生活变得更加轻松。 基于主题的编辑是你应该考虑的另一个重要原则。你的技术文档应该能解决用户的问题。因此,你可以将信息组织成一些主题或一些小节。比如安装,配置,升级,用户管理,故障排除等。在这一部分逻辑要相当清晰。但有时,当所描述的问题过于复杂时,仅仅将信息进行分节是不够的。在这种情况下,你需要根据客户的实际需要创建多级的节和主题逻辑结构,而节的划分将取决于情况。 总结 所以,要创建有用的技术文档,需要执行以下操作: 定义要解决的用户痛点 使你的内容同时具有可操作性和任务导向性 在结构创建上投入足够的时间和精力,这是非常重要的一点 技术文档工程师不是简单地创建内容,他们帮助人们使用软件和服务,向他们阐释信息。祝你能为你的读者写出有用的,高质量的内容。 祝你的技术写作顺利! ClickHelp(单击帮助)小组 编写,托管和交付文档的跨平台和设备

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

阅读原文