通过我们的分步指南,您将学习如何为任何项目编写有效的技术文档计划。 理想情况下,每个软件项目都应附有全面的技术文档,详细说明代码库的所有内部工作原理,并解释软件的架构、设计选择和编码约定。 因此,它们对于软件开发团队来说是非常有用的文档和宝贵的资产。 然而,您如何开始您的文献项目?您如何组织写作过程? 一个很好的起点是制定技术文档计划:文档编写过程的大纲。 如果您需要有关如何做到这一点的指导,请不要担心——本文适合您。继续阅读以了解如何编写出色的技术文档计划。 确定目标受众 制定高质量技术文档计划的第一步是确定您为谁撰写。谁将阅读文档计划? 例如,为公司内部的产品经理和外部利益相关者撰写的文章存在显著差异。 前者可能熟悉贵公司的标准流程和工作流程,而后者可能对这些概念完全不熟悉。
方想象下如果您的文档计划是为您的技术作家
团队编写的。 这样,它可能会非常不正式,但可能比针对高层管理人员的内容更为详细。 要确定文档计划的目标受众,请问自己以下问题: 要确定文档计划的目标受众需要问的问题 来源知识进行量身定制。 话虽如此,还需要考虑技术知识。你的 WhatsApp 号码数据 读者对专业术语有多熟悉?他们会理解常见的软件文档术语吗? 这些都是在编写文档计划时需要评估的重要因素。 然而,根据一般经验法则,最好听取专业作家 Jory MacKay 的建议: 技术写作的黄金法则是:“不可假设”。你可能认为自己说得很明显,但你必须了解你的读者的知识水平。 换句话说,你应该注意他们的技术熟练程度。
如果读者可能不是技术人最好谨慎行解释首
字母缩略词,避免使用缩写,并花点时间理解技术概念。 您的文档计划的读者将会对此表示感谢。 概述文档计划的范围 确定了写作对象后,就该确定写作内容了。文档计划将涉及哪些内容?必须包含哪些主题? 相反,有哪些主题可以省略? 换句话说,您需要 美国电话列表 概述文档计划的范围。 例如,您是否会编写一份适用于所有项目的通用文档,还是为某个特定项目定制文档? 文档计划是否涵盖测试文档和标准技术文档? 定义这些参数对技术作家来说非常有帮助。了解写作范围是成功的一半;有了明确的指导方针,实际写作过程应该会很快。 哈佛大学教,工作流程的关键就在于了解期望是什么。 如果您的技术作家知道既定的范围,他们在编写文档计划时可以更有效率。
而且他们并不是唯一从这些知识中
受益的人。为什么不也将其传达给你的受众呢? 这样,他们就知道会发生什么,并且可以轻松判断该计划是否会使他们受益。 塔克商学院教授斯科特·安东来源:哈佛商业评论 在文档计划的开头插入目录或写范围说明。 这篇简短的文章将会告诉读者 人与人的沟通,联系我们 文档计划中包含的具体内容,他们将能够快速判断该文档是否对他们有用。 创建文档计划大纲 现在您已经定义了范围,您终于可以组织文档计划了。最简单的方法是创建一个大纲;一份内容组织方式的草稿。 这样的大纲确保文档计划的安排合乎逻辑。不会有任何随意的主题变化,并且每个部分都应该直观地相互衔接。 构建大纲时,请尝试遵循倒金字塔方法。 这种方法是一种信息架构策略,首先阐明最重要的见解,然后扩展到细节,最后列出次要信息。
以下是一个直观的表 倒金字塔方法论的视觉表
示 来源的文档计划中,在深入探讨细节之前,金字塔的底部可能构成了文档的目的、范围和目标。 然后,在您的文档计划结束时,您可以包括词汇表、参考书目和类似内容(金字塔的顶端)。 有关在文档计划大纲中应纳入哪些内容的更多想法,请查看下图。它显示了文档计划的所有标准组成部分: 文档计划的组成部分 来源档计划至少应包含上面列出的部分。 它们包含在大多数文档计划中并且是概述您自己的文档的一个很好的起点。 此外,视觉遵循倒金字塔结构。 首先介绍基本信息(封面、联系信息、摘要),然后深入探讨有限的细节,例如技术文档规格。 通过遵循这些指南和建议,您可以轻松创建出色的文档计划大纲。 确定计划的正确格式 定义文档计划大纲后,您必须决定如何呈现这些信息。
选择什么字体项目符号列表或编
号列表哪个更好?您会使用图表吗? 显示信息的方式有无数种,因此您必须为您的文档计划选择最佳的格式类型。 最简单的起点是排版。一般来说,两种字体系列是衬线字体和无衬线字体,均显示如下: Serif 和 Sans Serif 之间的区别 来源线字体包含装饰性的锥体,而无衬线字体则由没有装饰的清晰线条组成。 由于无衬线字体线条笔直,因此被认为更为正式,并常用于商业领域。因此,这种字体非常适合您的文档计划。 如果您的公司相对现代化,您可以使用衬线字体作为正文,但标题应保持无衬线字体。 这样,文件的主要标志就会显得专业。 对于内容本身,请考虑加入图表。
有时通过视不是通过书面文传达信息
更好,因为读者通常比文本更容易处理图像。 例如,云架构师 Lynn Langit 在她的文档中使用了图表。 方法如下: 我使用图表取得了很大成功。我为受众定制视图,即客户流程视图、开发人员视图、DevOps 视图等。此外,我喜欢将图表区域涂成红色 | 黄色 | 绿色,以快速显示状态。 借助颜色和自定义等用户友好元素,图表可以让您的文档计划更易于理解。
下图显示了这些资源的概览文档编写
资源概述 来写作、协作编辑以及无数其他功能。 有了这样的资源,您可以轻松创建漂亮的技术文档。 编写技术文档计划 由于您现在已经确定了所有可用资源,您最终可以开始编写文档计划。 经过这么多准备,您可能希望您的文档计划尽可能详尽。然而,这些文本越简短越好,越简洁越好。 如果您的文档计划太长,那么人们就不太可能读完整个文档,因为一天的时间是有限的。 此外,读者的浏览会变得更加困难,