最初发表于https://ninadpathak.com/articles/technical-documentation-template/.
创建文档往往会同时迫使几个决定:读者开始的地方,他们如何完成第一个任务,确切的细节属于哪里,以及当一步失败时如何恢复.
一个模板将第一个通过的时间减少为您可以检查和调整的结构。
我建立这个模板是为了解决一个狭义的问题:一个空的文档存储库让每个贡献者发明导航,页面责任,以及再次放行检查.
它提供5个焦点页,一个本地验证符,以及严格的构建路径,因此结构在产品特定写作开始前是有用的.
下载技术文档模板 下载模板 解开归档,然后用您产品中的证据替换占位符 。
其余章节显示每一页中属于什么以及如何核实结果。
技术文件模板应当包括的技术文件模板是产品或工程文件可重复使用的起始结构。
它应该告诉一个贡献者读者从哪里开始,他们在哪里完成任务,他们在哪里寻找稳定的细节,以及他们从已知的失败中恢复过来。
单靠目录无法做到这一点。
它可以在“开始”的一页上贴上标签,而不设定先决条件、经过测试的命令、预期结果或恢复路径。
起步器包含有5页,因为他们创建了完整的第一路由,而没有假装每个产品都需要同样的收藏.
页面阅读器任务 发布索引前要添加的证据 . md 选择第一个有用的任务 。
选择直接到右起页的路径 。 md 完成第一次设置 Prerequisites , 一个经过测试的命令, 期望的输出指南/ send- a- request. md 执行一个限定的任务 A 完整请求和响应或可观测的状态引用/配置 。
数字 找寻稳定的细节 名称,类型,默认, 和限制 排除出故障. md 从已知的故障中恢复 Symptom, 诊断检查, 原因, 和恢复 教程, 如何向导, 参考, 和解释服务于不同的读者需求.
此模板从一个更小的产品-docs系统开始,然后当一个概念比指令更需要时留下了添加解释的余地.
模板中包含的文件 存档包含Markdown源,MkDocs配置,一个验证器,和一个GitHub Actions部署工作流程.
这种布局使导航,源,验证,部署紧密相通.
文档不仅仅是Markdown文件的文件夹 。
这是一个有投入和检查的小型出版系统。
MkDocs使用相同的基本分块:一个配置文件定义了站点,一个docs目录包含源,而一个构建则产生静态输出.
将这些角色分开使断开的链接或缺失的导航目标更容易被定位.
将占位符转换成测试的第一个任务 以最小的动作开始 来证明您的产品是可用的 。
对于一个API来说,这可能是一个经认证的请求,退回已知的答复.
对于CLI来说,安装后可以安装一个安全指令.
就内部服务而言,这可能是达到健康终点的地方发展结构。
把开始的一页写下来 说明读者开始前需要什么,给出确切的行动,显示预期状态,并与下一项任务相接.
网钩产品提供了一个具体的例子。
一个模糊的模板可能会说,“构思出一个网点。” 相反,一个有用的任务页可以识别事件、端点 URL、签名保密要求、请求机体、成功响应以及如何检查失败的交付。
每个项目都会回答读者在完成任务时遇到的不同问题.
不要将每个选项移动到正在启动的页面中 。
将稳定的名称,类型,默认值,和限制值放入参考.
Frede 的 API 引用对于研究很有用, 因为读者可以从对象移动到终点和字段而不必遵循