php开辟文档编写技巧_轨范员若何编写嵬峨上且实用的技能文档

文章目录 [+]

根据过往的履历，技能文档一样平常会：

项目文档：

php开辟文档编写技巧_轨范员若何编写嵬峨上且实用的技能文档

用于开启新项目的整体概要文档，解释项目背景、成员、依赖关系、项目整体排期、里程碑等信息。

（图片来自网络侵删）

支配文档：

先容网站或系统如何进行支配，搭建运行环境，常日须要解释代码的Git仓库位置、数据库构造、Nginx/Apache配置、操持任务配置、其他配置，是否须要CDN或HTTPS等，以及把稳事变。

接口文档：

针对每个API接供词给的文档，解释接口地址，调用办法，接口参数，返回构造，非常情形等。

模板文档：

供应给前端利用的模板文档，解释每个网站页面会存在哪些变量、类型是什么、以及处理逻辑，方便前端进行渲染、展示和交互。

设计文档：

针对系统、子系统或某个功能模块的设计解释，从技能架构到软件设计，到数据库建模，以及核心技能的先容，性能剖析等，面向工具是相同专业的专业职员。

开拓文档：

针对每个开拓需求而编写的文档，解释需求的背景、当前需求的实现思路，并记录这个需求所产生的接口文档、模板文档、数据库变更、上线待办清单、代码仓库和相应的开拓分支，以及一些把稳事变，方便需求在开拓过程中，以及在测试联调过程中，有很好的文档进行备忘、沟通和回顾。
如果有依赖底层或第三方的接口，也应一并补充。
若有外部调用方，也应进行登记。

故障文档：

当涌现线上故障时，处理完毕后，应编写故障复盘文档，进行缘故原由剖析、思考改进方法、贴出关键的代码、交待故障发生以及处理的历史过程，方便团队进行回顾、学习和避免类似问题再次发生。

分享文档：

对新技能或已有技能的技能分享，例如：如何利用docker支配本地开拓环境。

新人文档：

为新加入团队成员而编写的新人指引教程，包括系统先容、该当开通哪些账号、碰着的一些常见问题、入周第一周该当做什么等。

除此之外，还有系统卖力人文档、数据库文档、版本文档、需求文档等，不一一列出。

文档编写的要点

牢记，编写文档的目的是为了让读者可以快速有效地获取他想知道的信息。

因此，文档编写规则第一条：要大略、清晰、明了。
不要为了凑字数而堆字数。

文档编写第二条：明确文档面向的读者和受众。
根据所编写的文档，判断紧张面向的受众是产品、技能、测试还是商务职员，只管即便利用他们所能理解和熟习的词汇和表达办法来表达。

文档编写第三条：供应必要的信息。
根据须要编写的技能类型，供应必要的信息，就像拍照拍照一样，有一些约定的拍照构图，例如：均衡式构图、对称式构图、对角线构图、三角形构图、九宫格构图等。
文档也是一样，不同文档须要包含的元素、标题和部分也有所不同。
然后当你熟习后，可灵巧安排文档的内容，以最为恰当的构造形式来表达。

文档编写第四条：排版与图片。
只管即便不要一味地只供应笔墨信息，这样会让读者看起来很压抑而且以为是“天书”。
该当适当留一些空行，让读者眼睛“安歇”下，对读者友好一些。
同时，供应一些代码片段、UML图片或干系的插图用于赞助解释。
补充一些参考的文献和资料。
排版上，进行分段，分章节部分，把稳对主要的信息高亮、加粗、或重复解释。

文档编写第五条：万事开头难。
很多技能职员以为编写文档比写代码还要难，还要头疼。
实在写文档和写代码是类似的，很难一开始就写出完美的文档。
该当是像写代码一样，一开始写得很丑陋，但没紧要，至少有内容了。
然后，可以不断重构文档，对短缺的信息补全，对多余的信息进行删除。
末了以为内容上OK的话，就可以再进行排版和润色，补充一些图片。
逐步的，在通过存心花韶光后，你的完美文档就逐步出来了。

利用主流的markdown格式进行文档编写

首先，向小白程序员先容一下markdown这种格式。
这是一种很主流的格式，Markdown是一种可以利用普通文本编辑器编写的标记措辞，通过大略的标记语法，它可以使普通文本内容具有一定的格式。
说白了，便是它可以再转换成HTML代码，最后进行文档排版。

现在，已经有很多平台都支持了markdown的格式。

例如，Gitlab、Github、Gee：

又如各大信息类平台：

图灵社区：

掘金：

另一方面，支持markdown的措辞、系统、IDE开拓环境、软件、平台和js编辑器也很丰富。

markdown格式也是很随意马虎理解的，例如大标题、小标题的格式：

# 一级标题## 二级标题### 三级标题#### 四级标题##### 五级标题###### 六级标题

其他格式可自行查阅各大资料解释。

利用本地文本编辑器编写markdown文档