1.使用VScode+AsciiDoc+drawio+PlantUML设计文档真香
2.Asciidoctor Maven插件使用
3.git的源码安装
4.程序员如何写好技术文档？建议收藏

使用VScode+AsciiDoc+drawio+PlantUML设计文档真香

       技术文档编写，如何以技术手段提升效率？让我们来看看这个强大的源码组合：VScode+AsciiDoc+drawio+PlantUML，让你的源码文档编写体验升级。

       首先，源码VScode作为开发者的源码首选工具，以其强大的源码网狐6603源码网盘代码编辑能力闻名，丰富的源码插件生态几乎覆盖所有语言开发，是源码前端开发的得力助手。它不仅是源码开发环境，也是源码文档编辑的得力后盾。

       接着是源码AsciiDoc，这个在Java社区广泛应用的源码文档格式，语法类似Markdown，源码但功能更全面。源码虽然上手可能需要一点学习，源码但其原生支持的特性如作者信息、版本管理、表格等，使得编写文档更为便捷。特别提醒，导出PDF时可能遇到乱码问题，需要调整VScode插件和字体设置，比如使用AsciiDoc主题下的字体方案。

       相较于Markdown，AsciiDoc像是一个更精简且功能强大的替代品。它无需额外学习HTML扩展，能直接满足大部分文档编撰需求。例如，jdk net包源码你可以在 AsciiDoc 中直接添加自定义块和文档引用，提高编写效率。

       draw.io作为在线流程图绘制工具，无需安装，浏览器就能使用。它支持各类图表类型，包括流程图、软件图等，甚至可通过VScode插件直接在编辑器内操作，十分方便。虽然在线版速度可能稍慢，但其灵活性让人印象深刻。

       对于需要高级图表的场景，如UML图，PlantUML是不二之选。它支持编码绘图，范围超出UML，让图形设计更专业。通过PlantUML中文官网，你可以找到更多关于它的详细信息。

       总结来说，这个组合——在VScode中编写AsciiDoc文档，结合drawio绘制图表，再加上PlantUML的图形支持，无疑为技术文档的编写增添了极大的便利。你可以在github.com/hangcheng/As...找到相关的源码示例，开始你的cf内存无视源码高效文档之旅吧。

Asciidoctor Maven插件使用

       在项目中，撰写文档以传播设计概念、开发经验和避免常见陷阱，至关重要。Asciidoc格式对非技术人员的友好度较低，与PDF和网页格式相比，其传播性和通用性较差。在基于JVM的项目中，利用Maven插件可将.adoc文件格式转换为PDF、HTML、EPUB等格式文件，提升文档的适应性和使用效率。

       快速入门指南

       项目结构、pom.xml配置以及执行mvn命令，是快速实现文件格式转换的基本步骤。HTML文件生成后，通过HTTP Server或Nginx等服务部署，甚至利用Jenkins实现自动化部署，以确保文档的便捷访问。

       生成PDF

       项目结构、pom.xml配置和执行mvn命令同样是生成PDF的关键步骤。然而，PDF格式插件可能存在中文字体缺失的问题，影响生成的PDF文件的显示效果。为解决此问题，可自定义fonts和themes，调整PDF格式。在线防伪查询源码有时，直接将asciidoctorj-pdf源码合并，手动构建依赖包，并将其放入私有仓库，亦是高效解决方案。

       常见问题与参考资料

       在使用过程中，可能会遇到各种问题，例如字体缺失、文件格式兼容性等。查阅相关资料，获取解决方案，有助于解决开发过程中遇到的具体问题。确保文档格式转换的顺利进行，提升项目文档的制作效率和质量。

git的安装

       在CentOS系统上，安装Git有两种常见方法：yum自动安装和源码编译安装。尽管yum安装方便快捷，但版本控制有限，因此，本文将重点介绍源码编译安装Git（以2..0版本为例）的详细步骤。

       首先，通过wget下载Git源码包：wget kernel.org/pub/software...

       接着，解压下载的文件：tar -xzvf git-2..0.tar.gz

       为了顺利编译，确保安装必要的依赖，运行以下命令安装gcc、openssl等：yum -y install gcc openssl openssl-devel curl curl-devel unzip perl perl-devel expat expat-devel zlib zlib-devel asciidoc xmlto gettext-devel openssh-clients libiconv autotools 有时可能需要移除yum已安装的Git，使用 yum remove git 。网站动态背景源码

       接下来，进入解压后的Git目录，执行编译安装：cd git-2..0 && make prefix=/usr/local/git install

       安装完成后，添加环境变量至系统配置文件中：vim /etc/profile，并在文件末尾添加 export PATH=$PATH:/usr/local/git/bin，然后执行source /etc/profile使更改生效，无需重启系统。

       最后，检查安装是否成功，只需运行 git --version，如果显示出Git的版本号，说明安装已完成。

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

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

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

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

       某某同事的感谢

       反驳不需要写文档的言论

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

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

       附议：为什么要看文档

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

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

       什么算好的技术文档

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

       文档&写文档的定义

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

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

       方法论基调

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

       结构

       本章节讨论了一份技术文档应该具备的各个单元，可以作为今后技术文档写作的框架或者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/...

       来源：慕课网