Close

创建更出色的文档

您刚刚启动了一个项目,现在正在准备交付文档,但您对成功完成此项目却感到心烦意乱。

乍看起来令人生畏?确实如此,但我们将在此处为您提供帮助!通过下文,您将找到一份有关文档的文档 [您没有看错]。这是一个包含专业提示的分步指南,可引导您完成整个过程。 让我们一起来完成这件事吧!


为什么我需要关注此问题?

简而言之,文档可以帮助人们完成既定任务。但是,和大多数妙不可言的事物一样,它的作用远超出仅仅帮助人们完成任务。文档可帮助用户和团队:

大幅节省精力

无需大量思考即可完成工作,有效节省精力。

保持一致性

确保以一致的方式为读者呈现相同的信息、流程和计划。

有效减少工作量

快速高效地加入团队成员,以便他们可以立即开始完成工作。

提升公司品牌形象

展现公司对外部客户和内部员工的支持和帮助。

若不展现有价值之处,则无法吸引人员的注意力。您的任务是塑造读者思考您所提供的信息的方式,并说明为什么他们需要关注这些信息。

文档是什么?

文档是指一系列文件。它们是普通最终用户的指南针。它们是软件工程师的手册。在技术性更强的领域,文档通常是软件随附的文本或插图。这些文档可作为参考指南,阐释具体工作原理、运作方式以及使用方法。软件团队在讨论产品要求、发行说明或设计规范时可能会参考文档。技术团队可以使用文档来详细记录代码、API,以及软件开发流程。在外部,文档的形式通常是面向系统管理员、支持团队和其他最终用户的手册和用户指南。

所有文档都应着力实现两大目标:

1. 通知用户

2. 支持用户成功完成某些任务

在文档的开篇首先要定义兴趣主题、目标或目的,以帮助受众立即了解他们正在阅读的内容。

文档类型

如前所述,文档(包括内部文档和外部文档)有各种形状和大小。不同类型的文档会有不同的语调、语气、格式、贡献者、受众和内容。最常见的类型包括:



内部文档
团队文档插图

团队文档

团队文档有助于阐明正在完成的工作,以便团队成员可以开展协作。此类文档的形式包括项目计划、团队时间表、状态报告、会议记录,以及团队需要发挥职能并高效开展工作所需要的任何其他内容。此类文档非常详细,可确保所有人保持同步。

参考文档插图

参考文档

参考文档可向公司介绍重要主题、流程和政策。此类文档包括人力资源部门制定的政策、雇用外部供应商的法律程序,或有关设置公司福利的操作方法文章。请记住,参考文档由一小群人为各种受众而编写,因此确保内容易于理解至关重要。

项目文档插图

项目文档

项目文档在本质上特定于项目,并提供了产品开发极其需要的结构。此类文档包括提案、产品需求文档、设计指南或草图、路线图以及开发所需的其他相关信息,并由项目经理、工程师、设计师等人编写。



外部文档
系统文档插图

系统文档

系统文档详细介绍了代码、API 和其他流程,告诉开发人员和程序员在开发特定软件时可以使用哪些方法和函数,以及相关的限制和要求。代码片段,例如示例 API 调用和响应,是此类文档的核心。

最终用户文档插图

最终用户文档

用户文档通常是可见性更高的文档类型。它应易于阅读和理解,并跟随软件的每个新版本进行更新。其形式包括自述文档、安装指南、管理员指南、产品知识库和教程(此类文档中最有帮助的文档)。而且,与参考文档一样,它是由少数作者为大量读者编写的,因此确保内容易理解也至关重要。

在文档中包含示例可为受众提供巨大价值。此类示例是帮助受众理解概念和想法的桥梁,并向读者展示您对所讨论的内容非常熟悉。

创建文档

其最终目标是确保文档对读者有用。我们在下文为您的文档提供了教程格式的文档(元方法),以帮助您更轻松地完成任务。

1. 研究

用户需要了解有关您的产品、项目或 API 的哪些信息?使用分析工具查看正在搜索的内容,浏览在线社区论坛和讨论组,并进行用户研究和可用性测试。确保您也了解自己的产品以及如何轻松阐释用户问题、新功能和工作流程。

2. 启动

在开篇时清楚说明文档所涵盖的内容,以及为什么它对读者来说很有价值。

3. 把握细节

创建大纲并草拟内容。使用适当的语调和语气书写(人性化的口吻!)并保持语言风格简洁一致。清晰地传达重要的详细信息。

4. 设置格式

整理您的页面,以确保其通篇都易于阅读和理解。删减不相关的内容,并使用图表、屏幕截图和图像等视觉元素来分解长篇内容。

5. 审阅

获取拼写、行文等方面的反馈。确保审稿人了解文档的目标。这将有助于发现晦涩的表达或指出缺失的步骤。

6. 发布

经过修改和编辑后,您的文档即可上线!发布您的作品,随时留意任何反馈和评论。创建文档并非一劳永逸!

最佳做法

如您所见,文档不只是把一堆说明和词汇堆砌在一起。朋友们,请放心,针对此问题存在合理的解决方案。创建文档后,以及在睡觉前和睡觉期间,请记住以下指导原则:

保持简短

您的文档应包含恰到好处的信息,以便用户在无需提交支持工作单的情况下完成工作。提供要点和选项,让读者进一步了解详情。

视觉元素是关键

为方便读者理解,视觉元素是关键。产品设计、代码示例、产品内演示、屏幕截图和视频教程在帮助读者充分理解概念、操作方法或待办事项方面发挥着重要作用。此外,请注意布局、易读性和易于消化的板块。

了解受众

从用户的角度出发。了解您的读者,从他们的角度来看待您的产品和文档。在决定如何写和写什么时,应始终以此为指导。

立即投入工作

出色的文档应该清晰简洁、信息丰富,最重要的是,它可为受众增加价值。探索团队协作软件(如 Confluence)以创建文档,节省在寻找合适工具上花费的时间,将更多时间用于实现目标。

了解更多