如何写一份优质技术文档

作者简介：

本文作者拥有区块链创新专利30+，是元宇宙标准化工作组成员、香港web3标准工作组成员，参与编写《数据资产确权与交易安全评价标准》、《链接元宇宙：应用与实践》、《香港Web3.0标准化白皮书》等标准，下面提供一些编写文档过程的而一些思考。

优质技术文档的要素

读者&&场景准确匹配

读者定位：了解你的目标读者，根据读者的特征选择合适的语言和详细程度来解释技术概念。

场景定位：场景不同，要求不同，材料的表达方式与粒度也不同

背景&&概念清晰

文档中需要对文章的背景做介绍，文章用到的专业术语需要加以说明

结构清晰&&突出重点

结构清晰：在写作之前制定一个清晰的大纲。确保你的技术材料有逻辑性和结构性

突出重点：使用加粗、斜体或其他方式使重要的概念或术语更加明显，以便读者能够快速捕捉到关键信息

可视化&&可读性

可视化：使用图表、图像和其他视觉元素来增强可视化效

可读性：使用段落、标题和子标题来组织内容确保技术材料具有良好的可读性。行文流程、简介明了

信息正确与准确

技术类文章，对技术原理描述需要准确，对一些采用的数据需要说明来源，并保证正确性，不能夸大效果，天马行空

读者定位与场景定位

读者定位：根据读者的特征，选择合适的语言和详细程度来解释技术概念

场景定位：场景不同，要求不同，以下场景举例、要求也不同，场景举例

1、内部的技术文档：按照部门的规范与要求来写，主要在部门内部流转

2、政府的项目汇报文档：以政府的八股文为主，有固定的句式

3、专利交底书：是给代理人(非技术人员)写，主要用于查重与写专利稿件。

背景介绍与名词解释

背景介绍：要考虑到技术应用的上下文环境，这个要交待清楚

名称解释：特定名词的使用要引出简要的注释，名词解释一般放在文章的前面

结构清晰

结构清晰的方法：思维结构化，在思考问题与梳理知识的时候做到结构化，然后写文章结构先行、

然后根据结构来检查内容，内容服务于结构。下面列了一些常见的编写方法

运用小标题：

1、体现文章结构，让读者对文章一目了然。

2、让读者快速定位想要的内容，提高阅读效率

突出重点的方法

突出重点有以下常见的方法：结构设计、放大&&颜色突出、适当留白、使用加粗或者斜体

用图表来可视化表达

可视化的好处：帮忙读者快速理解技术点，帮助记忆（科学依据，人脑对图片信息的接收程度要远大于文字）

优秀文档案例

名字	内容	优点	链接
STARKEX	StarkEx 利用 STARK 技术为DeFi 和游戏提供可扩展、自我托管的交易解决方案	结构清晰、图表丰富、讲解详细、排版合理	Introduction :: StarkEx Documentation
FISCO BCOS	国内知名的开源联盟链	内容覆盖全、结构清晰、排版舒适	https://fisco-bcos- documentation.readthedocs.io zh CN/latest/
CHAIN LINK	web3预言机系统	技术原理清晰、操作手册详尽	Chainlink Data Feeds | Chainlink Documentation

总结

写文章的好处

写文章是一个逼迫自己深入理解问题、把问题想清楚，整理好思路，并能清晰表达出来的过程。其本质是一种自我学习、自我提升、构建知识体系的最佳方法。

如何提高的写材料能力

1、刻意练习：设置目标持续练习写材料

2、迭代优化：文章也需要进行重构，不断迭代

3、阅读与学习：优秀的技术文章