在新的工作岗位上，虽然我的职位名称依然是技术文档工程师，但实际的职责要求，不是开发具体的文档，而是管理文档项目，进行文档设计，协助研发人员进行文档开发，最终保证文档交付质量。
一直以来，我都很有信心独立输出质量可靠的文档。但是，如何通过团队配合，在文档开发另有其人的情况下，最终保证文档质量呢？这无疑是一个新的挑战。——后续我也会把其中的经验和思考，整理分享。
近日，基于某产品已有文档，重新梳理了内容架构，为了向研发说明内容构建逻辑，便于其理解后进行后续内容开发，因此整理了操作类文档的基本内容架构及说明。在此也简单地做一分享。
在进行用户指南文档设计时，可结合产品实际，包含以下内容：
产品简介
介绍产品基本功能和特性。
使用限制
说明当前操作无法支持/适用的场景，包括但不限于：系统、环境等。
如产品/服务无法支持/适用用户期望场景，需提前告知，避免徒劳，即操作到一半，才发现无法使用的情况。
前提条件
说明执行当前操作需满足的条件，包括但不限于：权限、已完成的操作/配置。
考虑到，用户可能出现前提条件不满足的场景，需提供相关操作指导，便于用户实现前提条件所列要求。
提供相关操作指导可以采用2种方式：
增加准备工作章节，对实现前提条件的操作步骤，进行详细说明。
如当前文档其他章节已有操作指导，可添加跳转链接；如其他文档已有操作指导，可添加参考说明，索引到相关内容。
操作说明
结合典型使用场景，分场景说明操作原理、操作流程等，便于用户结合自身情况，选择适当方式进行操作，并了解操作逻辑。
内容包括但不限于：
场景说明：操作类文档的内容需基于使用场景展开。
操作原理说明：不建议说明功能实现原理，除非有助于用户进行操作。
操作流程说明：建议包括流程图；和分步说明。
操作说明与操作步骤为总分关系，操作流程的步骤需一一对应。
操作步骤
分步骤详细说明操作方法。
如可能造成操作失败（注意）、用户数据丢失（警示）、人员伤亡（危险）等潜在风险，需给予警示。
操作验证
（可选）指导用户验证操作是否达到既定目标，例如，功能配置等。
操作验证需充分考虑操作过程中可能出现的错误，提供排查和解决方法。
操作结果说明
（可选）对于操作完成后的结果，进行必要说明。例如，系统初始化后，说明初始配置等。
后续步骤
（可选）如完成当前操作后，需/可进行相关的后续操作，进行说明。
接口说明
（可选）如提供API接口支持二次开发，需给出说明；或提供单独的API接口参考文档。
错误码说明
（可选）在使用命令行进行操作的场景，系统常以编码形式反馈操作结果。在这种情况下，需说明系统反馈的错误码，以及排查处理方法。
其中尤以排查处理方法最为重要，帮助用户独立解决可能遇到的问题。
关键性能指标
（可选）如需对用户提供产品性能指标，需对其进行说明。
内容包括但不限于：
描述：说明性能指标衡量的内容。
统计方法/计算共识：说明性能指标统计方法或者计算共识。
参数数值：说明数值大小与性能高低的正反比关系。
术语表
解释文档中出现的复杂概念，同时确保文档中术语保持一致。
附录
其他参考类内容。
以上，仅针对操作类文档的基本内容架构进行说明，内容写作规范后续会另做整理分享。
其他推荐：
实施：GitHub + MarkDown 文档系统的工作环境部署及工作流程说明 | 技术传播
这次他们说好要“讲真的” | 传播
在座都别吵了，你们还有我 | 技术传播
睿齐
技术传播从业者
品牌内容策划
自由摄影师
自由撰稿人
汪力迪
公众号：techcomm / htstory
微信号：bgrichi
邮箱：hash_0813@163.com
扫一扫
1万+
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
