皮皮网

1.程序员如何写好技术文档？建议收藏
2.云计算要学习哪些知识呢？

程序员如何写好技术文档？建议收藏

       文档的范围很广，本文特指开发人员撰写的网权包含基本产品背景和主要技术设计的文档。

       世界观为什么要写技术文档？

       写技术文档可以帮助团队完成当前的限源信息共享和长期的知识传承。对个人而言，课网一方面可以节省时间，权限因为避免了回答重复问题，源码长沙到广州源码也便于检索过去的慕课码慕知识；另一方面可以塑造口碑，比如某次突然有同事给我发消息说我的网权文档写的很好，对新接触这块业务的限源人帮助很大。

       某某同事的课网感谢

       反驳不需要写文档的言论

       有很多程序员都持有一个观点：“不用看(写)文档，文档都在代码里”，权限还有一部分人认为，源码文档容易过时，慕课码慕很难跟上代码的网权更新节奏，因而没有必要写文档。限源

       对此，首先我个人认为涉及代码细节的部分确实没必要写文档，但是对于总体的设计和业务的变更是绝对需要写文档的。有些人觉得文档有过时问题，那是elementplus源码解读因为他们没有引入版本（ChangeLog）的概念，过时的文档本身就是业务历史的一部分。在接手一个业务的时候，常常就需要这些历史信息来辅助理解。

       附议：为什么要看文档

       上周发生了一件趣事，一个产品跟我说，开发两句话能说明白的，为什么要看文档？确实，问开发能以最快速度准确地获取信息，毕竟人脑就是一个强大的搜索引擎。但是长期来看有以下问题：

       一般来说，一份好的技术文档比起开发口述是不会有多余的理解成本的，甚至更低，因为对于很多信息，能比语言更好地表达。

       什么算好的技术文档

       我认为好的技术文档的核心是敏捷。一方面，好的的技术文档是高度可维护的并且经常维护的，比如新增了一些功能，文档的47模板源码作者能够快速更新文档，文档的读者能及时获取更新；另一方面，好的技术文档是易理解的，更详细来说要表述准确、结构清晰、排版美观、风格统一。

       文档&写文档的定义

       最后，我想探讨下写文档到底是干吗？百度百科说：软件文档或者源代码文档是指与软件系统及其软件工程过程有关联的文本实体。那么写文档就是生产这个实体的过程了。但这样实在过于抽象，根据我最近一年的经验来看，我更愿意将其定义为对特定信息进行结构化整理的过程。

       以上就是写作技术文档的道了，也就是我们对于这件事最基础的世界观，接下来谈术，即基于此执行的方法论。

       方法论基调

       在正式开始写文档之前，我们必须要有以下三点认知：

       结构

       本章节讨论了一份技术文档应该具备的各个单元，可以作为今后技术文档写作的最新itvbox源码框架或者Checklist。

       Introduction

       简单介绍项目背景信息，如下面是我为某个项目写的 Introduction ：

       Content

       目录，目录是结构的直接体现，必须有，一般文档写作工具都能自动生成：

       Terms

       术语解释，很多业务会衍生一些特定词汇，如“白条卡”、“大图卡”等，都是有特定语境的，需要单独解释。

       Setup

       如何运行这个项目，一般开源项目都会有，如果是SDK文档也常常有接入文档，就是这个模块。

       Body

       这部分就是文档的主体部分，具体结构需要视内容而定，有以下通用规则

       对于具体的格式规范，推荐阅读 ruanyf/document-style-guide: 中文技术文档的写作规范。

       Reference

       这部分也可以放在附录里面，股精源码见下图。

       FAQ

       其他人经常问的问题，遇到就记录在这个模块，不断补充，日趋完善。

       Appendix

       一些比较冗长的信息可以放在附录里面，比如日志，避免放在正文影响排版和阅读。

       ChangeLog

       变更日志，一般开源项目都会记录每个版本的重要变更。

       ReleaseNote

       发版日志，一般开源项目都会有一个单独的Release页面。

       过程

       一般来说，文档写作的流程如下：

       收集信息、整理框架、实践结论、写作文档。如果前期工作足够，写作所花的时间是很少的。此外，文档完成后，还要注意读者反馈，以不断完善自己的文档。写一份好的技术文档也不是一蹴而就的，需要不断打磨，要注意经常去刻意练习。

       工具

       写作工具

       一般来说，只要别人发给我的文档是一份Word文档，我基本就把这份文档排在了最LowB的一档。对于这种文档，我就想问两点：为什么不是Markdown或Asciidoc格式？Markdown比较受开源社区的欢迎，因为它在表达力和简洁性之间找到了一个平衡点，但是它有一个致命问题就是无法应付稍微复杂一点的排版。Asciidoc则是我的主力文档工具，很多人不知道Github也是支持这种文档格式的，比如本文就是这种格式的。Asciidoc的语法比Markdown更加复杂，但我认为牺牲一点时间学习是完全值得的。最后是Latex，Tex的变种，表达力最强大，可以应付各种复杂排版，一般在学术圈比较流行（尤其是那些复杂数学公式的表达），但我认为放在日常的文档写作中有点矫枉过正了。

       维护工具

       对于文档的管理，我推荐使用Git，像管理代码一样管理文档。另外我推荐使用一个静态网站来存放自己的文档，这样其他同事访问的时候看到的总是最新的文档了。另外，公司目前在推iWiki，我觉得iWiki最大的优势是权限控制，对于一些敏感文档是必须的。但是，比起iWiki的变更记录，作为程序员的我更钟爱用Git进行管理，此外，iWiki是Web网页，编辑体验肯定也比不上本地自己配置的编辑器。当然，术没有绝对的优劣之分，也要看自己是否合适。

       总结

       以上，最近关于技术文档写作的一些思考。欢迎交流指正。

       作者：慕用

       链接：imooc.com/article/...

       来源：慕课网

云计算要学习哪些知识呢？

云计算第一阶段：主要学习网络基础，包括计算机网络(以太网、TCP/IP网络模型)、云计算网络(网络QoS、交换机与路由器)，配备有企业级项目实战：IP地址配置与DNS解析。

云计算第二阶段：学习Linux基础，包括Linux操作系统(文件权限、作业控制与进程管理)以及Linux高级管理(Sed、Awk工具、源码编译)。企业级项目实战为：云数据中心主机CPU资源利用率实时统计、分析系统。

云计算第三阶段：学习Linux运维自动化，企业级项目实战为Python+Shell实现企业级FTP文件统一管理。

云计算第四阶段：数据库运维管理的学习，企业级项目实战：MySQL Galera高可用集群环境部署、异步消息队列集群RabbitMQ部署与运维。

云计算第五阶段：企业级云架构管理与综合实战(PaaS+TaaS)，项目训练的是基于LAMP架构实现云计算PaaS平台典型应用部署与运维，通过Nginx实现千万级并发访问处理。

       Linux操作系统高效率、应用广，适用于各种设备中，在国内Linux的人才缺口逐渐扩大，就业方向多、岗位充足：

有云计算方向、DBA方向、安全运维方向、系统运维方向、Python运维开发方向等。

       linux学完可以选择的工作岗位更是多种多样，云计算工程师、云计算研发工程师、云计算架构师、数据库运维工程师、高级数据库工程师、数据库架构师、安全运维工程师、安全专家、安全架构师、系统运维工程师、高级系统运维工程师、系统运维技术专家、Python运维开发工程师、Python高级运维开发工程师、技术总监等。