##### 规范文档指南 - 规范文档 - 尽早适应阅读和编写文档是一项非常重要的技能, 虽然在工作中写文档是一个 `dirty work` 脏活累活, 但是在技术领域和团队协作中, 文档不仅是知识的载体, 也是沟通和协作的桥梁, 写文档是不可避免的. [wik](https://en.wikipedia.org/wiki/Wiki) 是互联网上超文本文档出版的一种形式, 拥有众多社群, 很多企业也有内部 `wiki`. 我认为文档形式或者结构基本上决定了文档的下限, 但是上限永远由内容决定 - 规范文档编写 - 一致性 - 文档内所有词语, 符号保持概念一致, 所有格式, 样式保持风格一致, 对于具有格式化数据的页面应使用页面模板 - 定位 - 文档定位不同意味着不同的内容和结构规范, 例如项目文档, 设计文档, 计划文档, 技术文档, 接口文档, 产品文档, 规范文档, 需求文档, 用户文档, 帮助手册, 教程文档, 日志文档, 信函文档, 演示文档, 论文文档等等 - 结构 - 文档结构包括页面结构和内容结构, 页面结构指所有页面的组织和分类, 页面组织可以是线性和非线性的, 页面分类是对页面记载内容和承担功能的划分, 内容结构指文档主体撰写的主题思路, 抽象层次和交叉引用. 规范的结构利于文档更新与维护 - 语言 - 文档语言应保持简洁, 清晰, 准确, 做到严谨与通俗并存, 适当予以注释 - 图表 - 文档应通过图表简化复杂内容, 例如流程图, 模型图, 表格等 - 元数据 - 页面元数据是关于页面的描述信息, 例如内容, 结构, 版本, 作者及其相关特性等 - 版本管理 - 大型文档应该对每个页面进行版本管理, 包括版本编号和版本记录 - 权限管理 - 定义不同用户的权限级别, 采用分层权限管理策略, 确保敏感内容的访问受控 - 审核校对 - 制定文档的审核流程, 包括技术审核, 语言校对, 设计评估等 - 规范文档示例 - [devdocs 文档集](https://devdocs.io/) - [github 文档](https://docs.github.com/en) - [vuejs 文档](https://vuejs.org/api/) - [django 文档](https://docs.djangoproject.com/en/5.1/) - [docker 文档](https://docs.docker.com/) - [microsoft 文档](https://support.microsoft.com/) - [matlab 文档](https://www.mathworks.com/help/) - [autocad 文档](https://help.autodesk.com/) - 规范文档生成