程序员如何编写高大上且实用的技术文档--转

原文链接:https://blog.csdn.net/qq_17324713/article/details/105895720?utm_term=%E7%A0%94%E5%8F%91%E6%8A%80%E6%9C%AF%E6%96%87%E6%A1%A3%E7%BC%96%E5%86%99&utm_medium=distribute.pc_aggpage_search_result.none-task-blog-2_allsobaiduweb~default-0-105895720&spm=3001.4430

如何编写高大上的技术文档

作为程序员，除了会写代码，能查bug，还要会画图（UML建模）、做PPT（分享、述职等），更重要的是还要能写得出文档，并且能写出高大上的文档。

 

根据过往的经验，技术文档一般会：

项目文档：

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

部署文档：

介绍网站或系统如何进行部署，搭建运行环境，通常需要说明代码的Git仓库位置、数据库结构、Nginx/Apache配置、计划任务配置、其他配置，是否需要CDN或HTTPS等，以及注意事项。

接口文档：

针对每个API接口提供的文档，说明接口地址，调用方式，接口参数，返回结构，异常情况等。

模板文档：

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

设计文档：

针对系统、子系统或某个功能模块的设计说明，从技术架构到软件设计，到数据库建模，以及核心技术的介绍，性能分析等，面向对象是相同专业的专业人员。

开发文档：

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

故障文档：

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

分享文档：

对新技术或已有技术的技术分享，例如：如何利用docker部署本地开发环境。

新人文档：

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

 

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

文档编写的要点

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

 

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

 

文档编写第二条：明确文档面向的读者和受众。根据所编写的文档，判断主要面向的受众是产品、技术、测试还是商务人员，尽量使用他们所能理解和熟悉的词汇和表达方式来表达。

 

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

 

文档编写第四条：排版与图片。尽量不要一味地只提供文字信息，这样会让读者看起来很压抑而且觉得是“天书”。应该适当留一些空行，让读者眼睛“休息”下，对读者友好一些。同时，提供一些代码片段、UML图片或相关的插图用于辅助说明。补充一些参考的文献和资料。排版上，进行分段，分章节部分，注意对重要的信息高亮、加粗、或重复说明。

 

文档编写第五条：万事开头难。很多技术人员觉得编写文档比写代码还要难，还要头疼。其实写文档和写代码是类似的，很难一开始就写出完美的文档。应该是像写代码一样，一开始写得很丑陋，但没关系，至少有内容了。然后，可以不断重构文档，对缺少的信息补全，对多余的信息进行删除。最后觉得内容上OK的话，就可以再进行排版和修饰，补充一些图片。慢慢的，在通过用心花时间后，你的完美文档就慢慢出来了。

 

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

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

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

例如，Gitlab、Github、Gee：

 

又如各大信息类平台：

图灵社区：

 

掘金：

 

 

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

 

 

markdown格式也是很容易理解的，例如大标题、小标题的格式：

  
  

    
    

     
     

    
    
    
    

     
     

      
      #
      
       一级标题
     
     
    
    

    
    

     
     

    
    
    
    

     
     

      
      #
      
      # 二级标题
     
     
    
    

    
    

     
     

    
    
    
    

     
     

      
      #
      
      ## 三级标题
     
     
    
    

    
    

     
     

    
    
    
    

     
     

      
      #
      
      ### 四级标题
     
     
    
    

    
    

     
     

    
    
    
    

     
     

      
      #
      
      #### 五级标题
     
     
    
    

    
    

     
     

    
    
    
    

     
     

      
      #
      
      ##### 六级标题 
     
     
    
    
  
  

其他格式可自行查阅各大资料说明。

 

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

不管你用的是windows系统，还是Linux，还是Mac手提，都有很多文本编辑器是支持markdown的编写以及预览。

 

markdown文档的后缀名是md，例如常见的顶顶有名的README.md。

 

例如我在Macbook上使用SubEthaEdit：

 

编辑界面如下（后面可以看到相应的访问效果）：

 

在编辑时，编辑器会自动帮你进行markdown格式的高亮，非常友好。

 

SubEthaEdit官方的介绍。

 

使用docsify搭建你的文档网站

了解完伟大的markdown格式后，接下来你就可以使用docsify把写好的markdown文档进行在线展示了。

docsify是一个基于javascript运行的开源项目，不需要任何PHP、java、数据库后端的依赖，就可以直接展示你的在线文档。

 

docsfiy官网：https://docsify.js.org/#/?id=docsify-4113

显示效果：

 

来一个更完整的文档截图：

 

不用担心英文的问题，文档上的内容都是可以自己设置和编写的。

 

docsify支持文档搜索、左侧菜单、顶端菜单、封面等。

 

例如，PhalApi开源框架使用docsify搭建的效果：

项目封面：

 

文档正文：

 

搜索效果（留意左边）：

 

 

同时完美支持移动端访问文档：

 

用果创云文档编写你的技术文档

最后，如何你不想搭建自己的文档网站，也可以直接使用果创云的在线文档，来编写自己的技术文档，分享你需要分享的项目成员查看。

 

果创云在线文档就是基于docsify搭建和markdown格式来编写的。

 

首先，进入果创云开放平台：http://open.yesapi.cn

 

然后，进入【文档】：http://open.yesapi.cn/wiki/home

 

 

进入后，便可以创建你的项目文档，支持创建多个项目文档。

 

接着，就可以在线编辑你的文档，并且实时预览。

 

 

编写完成后，就可以查看你的文档。

 

文档展示效果：

 

 

为保护你的文档，你可以设置项目文档的查看密码：

 

这时候，需要填写密码才能查看你的文档：