程序员如何编写高大上且实用的技术文档
如何编写高大上的技术文档
作为程序员，除了会写代码，能查bug，还要会画图（UML建模）、做PPT（分享、述职等），更重要的是还要能写得出文档，并且能写出高大上的文档。
根据过往的经验，技术文档一般会：
项目文档：用于开启新项目的整体概要文档，说明项目背景、成员、依赖关系、项目整体排期、里程碑等信息。
部署文档：介绍网站或系统如何进行部署，搭建运行环境，通常需要说明代码的Git仓库位置、数据库结构、Nginx/Apache配置、计划任务配置、其他配置，是否需要CDN或HTTPS等，以及注意事项。
接口文档：针对每个API接口提供的文档，说明接口地址，调用方式，接口参数，返回结构，异常情况等。
模板文档：提供给前端使用的模板文档，说明每个网站页面会存在哪些变量、类型是什么、以及处理逻辑，方便前端进行渲染、展示和交互。
设计文档：针对系统、子系统或某个功能模块的设计说明，从技术架构到软件设计，到数据库建模，以及核心技术的介绍，性能分析等，面向对象是相同专业的专业人员。
开发文档：针对每个开发需求而编写的文档，说明需求的背景、当前需求的实现思路，并记录这个需求所产生的接口文档、模板文档、数据库变更、上线待办清单、代码仓库和相应的开发分支，以及一些注意事项，方便需求在开发过程中，以及在测试联调过程中，有很好的文档进行备忘、沟通和回顾。如果有依赖底层或第三方的接口，也应一并补充。若有外部调用方，也应进行登记。
故障文档：当出现线上故障时，处理完毕后，应编写故障复盘文档，进行原因分析、思考改进措施、贴出关键的代码、交待故障发生以及处理的历史过程，方便团队进行回顾、学习和避免类似问题再次发生。
分享文档：对新技术或已有技术的技术分享，例如：如何利用docker部署本地开发环境。
新人文档：为新加入团队成员而编写的新人指引教程，包括系统介绍、应该开通哪些账号、遇到的一些常见问题、入周第一周应该做什么等。
除此之外，还有系统负责人文档、数据库文档、版本文档、需求文档等，不一一列出。
文档编写的要点
切记，编写文档的目的是为了让读者可以快速有效地获取他想知道的信息。
因此，文档编写规则第一条：要简单、清晰、明了。不要为了凑字数而堆字数。
文档编写第二条：明确文档面向的读者和受众。根据所编写的文档，判断主要面向的受众是产品、技术、测试还是商务人员，尽量使用他们所能理解和熟悉的词汇和表达方式来表达。
文档编写第三条：提供必要的信息。根据需要编写的技术类型，提供必要的信息，就像摄影拍照一样，有一些约定的摄影构图，例如：均衡式构图、对称式构图、对角线构图、三角形构图、九宫格构图等。文档也是一样，不同文档需要包含的元素、标题和部分也有所不同。然后当你熟悉 后，可灵活安排文档的内容，以最为恰当的结构形式来表达。
文档编写第四条：排版与图片。尽量不要一味地只提供文字信息，这样会让读者看起来很压抑而且觉得是“天书”。应该适当留一些空行，让读者眼睛“休息”下，对读者友好一些。同时，提供一些代码片段、UML图片或相关的插图用于辅助说明。补充一些参考的文献和资料。排版上，进行分段，分章节部分，注意对重要的信息高亮、加粗、或重复说明。
文档编写第五条：万事开头难。很多技术人员觉得编写文档比写代码还要难，还要头疼。其实写文档和写代码是类似的，很难一开始就写出完美的文档。应该是像写代码一样，一开始写得很丑陋，但没关系，至少有内容了。然后，可以不断重构文档，对缺少的信息补全，对多余的信息进行删除。最后觉得内容上OK的话，就可以再进行排版和修饰，补充一些图片。慢慢的，在通过用心花时间后，你的完美文档就慢慢出来了。
使用主流的markdown格式进行文档编写
首先，向小白程序员介绍一下markdown这种格式。这是一种很主流的格式，Markdown是一种可以使用普通文本编辑器编写的标记语言，通过简单的标记语法，它可以使普通文本内容具有一定的格式。说白了，就是它可以再转换成HTML代码，最后进行文档排版。
深圳SEO优化公司天津企业网站制作推荐焦作企业网站制作哪家好济源企业网站设计哪家好肇庆SEO按天计费推荐广元关键词按天计费松岗网站建设设计公司海西网络广告推广价格昌都百度标王价格沈阳网络营销温州网站设计多少钱来宾seo推荐包头企业网站制作价格镇江优秀网站设计公司德阳SEO按天计费哪家好清徐网站制作设计哪家好文山SEO按天扣费濮阳至尊标王哪家好汕尾网站优化按天扣费公司鄂州网站开发公司霍邱网站设计价格咸宁企业网站建设辽源网站排名优化公司罗湖网站改版多少钱海东网站推广系统哪家好巴中网站改版推荐黔南网站定制推荐玉树网站改版推荐武汉百度网站优化价格濮阳网站seo优化报价塘坑外贸网站设计公司歼20紧急升空逼退外机英媒称团队夜以继日筹划王妃复出草木蔓发 春山在望成都发生巨响 当地回应60岁老人炒菠菜未焯水致肾病恶化男子涉嫌走私被判11年却一天牢没坐劳斯莱斯右转逼停直行车网传落水者说“没让你救”系谣言广东通报13岁男孩性侵女童不予立案贵州小伙回应在美国卖三蹦子火了淀粉肠小王子日销售额涨超10倍有个姐真把千机伞做出来了近3万元金手镯仅含足金十克呼北高速交通事故已致14人死亡杨洋拄拐现身医院国产伟哥去年销售近13亿男子给前妻转账 现任妻子起诉要回新基金只募集到26元还是员工自购男孩疑遭霸凌 家长讨说法被踢出群充个话费竟沦为间接洗钱工具新的一天从800个哈欠开始单亲妈妈陷入热恋 14岁儿子报警#春分立蛋大挑战#中国投资客涌入日本东京买房两大学生合买彩票中奖一人不认账新加坡主帅：唯一目标击败中国队月嫂回应掌掴婴儿是在赶虫子19岁小伙救下5人后溺亡 多方发声清明节放假3天调休1天张家界的山上“长”满了韩国人？开封王婆为何火了主播靠辱骂母亲走红被批捕封号代拍被何赛飞拿着魔杖追着打阿根廷将发行1万与2万面值的纸币库克现身上海为江西彩礼“减负”的“试婚人”因自嘲式简历走红的教授更新简介殡仪馆花卉高于市场价3倍还重复用网友称在豆瓣酱里吃出老鼠头315晚会后胖东来又人满为患了网友建议重庆地铁不准乘客携带菜筐特朗普谈“凯特王妃P图照”罗斯否认插足凯特王妃婚姻青海通报栏杆断裂小学生跌落住进ICU恒大被罚41.75亿到底怎么缴湖南一县政协主席疑涉刑案被控制茶百道就改标签日期致歉王树国3次鞠躬告别西交大师生张立群任西安交通大学校长杨倩无缘巴黎奥运