如何编写技术文档

主要观点总结

本文主要讨论了软件系统中技术文档的编写与组织。文章提到了编写技术文档的重要性以及面临的挑战，如文档的混乱结构、多人编写导致的混乱等。文章介绍了两种组织文档的方法：结构化文档和图形化文档，并讨论了各自的优缺点。此外，文章还涉及了如何选择适合的文档工具或协作平台，以及一些具体的文档构建解决方案，包括sphinx + Document Zenith + Git和logseq等方案的优缺点。最后，文章强调了文档构建也需要满足一些非功能性需求。

关键观点总结

关键观点1: 技术文档在软件开发中的重要性及其面临的挑战。

文章强调了软件产品的优秀程度并不是唯一重要的因素，好的技术文档同样至关重要。但是，技术文档的编写面临着如仓促开始和结束、混乱的结构、多人编写导致的混乱等挑战。

关键观点2: 两种组织文档的方法：结构化文档和图形化文档。

文章介绍了结构化文档和图形化文档的优缺点，并指出结构化文档是目前最主流的文档组织方式，而图形化文档则更符合人类在大脑中构建知识模型的方式。

关键观点3: 如何选择适合的文档工具或协作平台。

文章讨论了在构建文档时需要考虑的一些因素，如可移植性、可用性、合规性、可访问性等非功能性需求，并介绍了一些常用的文档工具如sphinx、Document Zenith、logseq、Google Docs和Confluence等，及其优缺点。