程序员如何编写高大上且实用的技术文档--转
原文链接: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-2allsobaiduweb~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
进入后,便可以创建你的项目文档,支持创建多个项目文档。
接着,就可以在线编辑你的文档,并且实时预览。
编写完成后,就可以查看你的文档。
文档展示效果:
为保护你的文档,你可以设置项目文档的查看密码:
这时候,需要填写密码才能查看你的文档:
程序员如何编写高大上且实用的技术文档--转相关推荐
- 程序员突破年薪50万的唯一门坎-文档写作能力(一)
第一篇算是一个导论 不知道大家有没有经常回溯.追溯或者抱怨过这样的内容. 第一种抱怨:工作了4年.5年,晋升不明显,最最多做到一个小Team Leader,管了3-5个人.跳来跳去工资增涨只不过多个2 ...
- css 图片换行_好程序员web前端学习路线分享CSS浮动-文档流篇
1.纯文本的排列. 文档流就像我们的文本内容一样,所有的文字都会紧挨着,一个个排列下来,如果到了边界,就会换一行排列.当然如果敲回车或者按下空格键一般都会认为是一个词间距,因为英文中每个单词之间是有距 ...
- PHP新闻APP,【优速软件】APP/小程序接口:全部新闻列表,POSCMS,CodeIgniter技术文档,PHP开发文档,迅睿CMS框架官方教程...
请求地址格式: 本部分内容设定了隐藏,需要回复后才能看到,立即回复 那么,新闻模块news格式为:http://网站/index.php?s=news&c=search&auth=授权 ...
- 程序员职业技能编写_程序员不需要的不需要编写代码的技能
程序员职业技能编写 You can build the best application in the world, but if you don't know how to tell anyone ...
- 适合程序员、办公人员的实用工具
适合程序员.办公人员的实用工具 前言 在我们日常的办公当中总会有一些比较繁琐的步骤流程需要重复的执行,非常耽误我们的时间,以下推荐几款非常实用的软件辅助办公. 1.uTools 官网:uTools官网 ...
- 程序员代码编写_我如何不编写协作写作应用程序的代码
程序员代码编写 葵仓,句,但更有趣 (Twaikura, haikus but funnier) As easy as ABC: some stranger on the Internet start ...
- 程序员都应当知道的实用工具网站
程序员都应当知道的实用工具网站 1.搜索引擎 1-1 秘迹搜索 1-2 小白盘 1-3 DogeDoge搜索 1-4 百谷歌度搜索 2.变量取名工具 2-1 Codelf 3.PPT 3-1 优品PP ...
- 干货 | 程序员必备的16个实用的网站
最近看到很多网友分享了好多比较酷炫的网站,好多都放进小艾的收藏夹了,(__) 嘻嘻--看的我也忍不住想分享了,因为是IT行业,所以分享几个收集的比较实用而且酷炫的网站O(∩_∩)O~ 1." ...
- 美团大咖:程序员35岁前应做好的技术积累
刘丁 读完需要 26 分钟 速读仅需 9 分钟 引言 古人云:"活到老,学到老."互联网算是最辛苦的行业之一,"加班"对工程师来说已是"家常便饭&qu ...
最新文章
- html使用xml数据岛,html中的xml数据岛记录编辑与添加_xml技巧
- python与excel的区别-python比较两个excel表格的差异
- 决策树 bagging boosting 的区别
- CentOS7安装cuda及GPU驱动--基于runfile文件
- 【Nginx】初探 Nginx 架构
- 机器视觉行业市场现状及发展前景分析
- 计算机技术级生活中的应用,人工智能技术在计算机中的发展与应用
- Hive报错:Exception in thread main java.lang.Incom。。。。 Class com.google.common.collect.ImmutableSotil
- 二叉树学习之非递归遍历
- 玩转keybd_event
- Web.py Cookbook 简体中文版 - 在webpy中使用Cheetah模板引擎
- Crystal Reports基础知识
- 真实业务订单 拆单 架构与实战
- 极域课堂管理系统软件如何取消控制_青岛海运职业学校智能用电管理平台系统建设项目完成验收...
- .Net Core Win2008R2 运行环境问题 502.5
- oracle odi 资料档案库访问期间出现未分类的异常错误,ODI11g问题汇总
- React 备忘录 v16
- 安恒2020-四月春季战-reverse-sm
- DM642的PCI驱动编程笔记:详述DM642的PCI接口的地址映射机制
- 电脑游戏测试cpugpu软件,【七彩虹GTX760评测】七彩虹iGame760烈焰战神规格介绍-中关村在线...
热门文章
- 群晖nas免费内网穿透,实现外网异地远程访问
- 庄子心得06:总有路可走
- 华为HCIE认证改版(2021年5月30日正式改版升级)
- 模糊集合和隶属度详解
- 仿b站的动漫视频网站
- CC00082.spark——|HadoopSpark.V08|——|Spark.v08|Spark 原理 源码|Spark Context|
- CSS制作的32种图形效果 梯形 | 三角 | 椭圆 | 平行四边形 | 菱形 | 四分之一圆 | 旗帜
- 今天又接到了交通罚单
- python处理pdf文件的程序_Python处理PDF文档-拆分合并
- 易语言单窗口单进程单IP技术