如何写一份优质技术文档

作者简介:

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

优质技术文档的要素

读者&&场景准确匹配

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

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

背景&&概念清晰

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

结构清晰&&突出重点

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

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

可视化&&可读性

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

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

信息正确与准确

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

读者定位与场景定位

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

场景定位:场景不同,要求不同,以下场景举例、要求也不同,场景举例

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

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

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

背景介绍与名词解释

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

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

结构清晰

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

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

运用小标题:

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

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

突出重点的方法

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

用图表来可视化表达

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

优秀文档案例

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

总结

写文章的好处

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

如何提高的写材料能力

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

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

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

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/pingmian/62424.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

【Git】Git 完全指南:从入门到精通

Git 完全指南:从入门到精通 Git 是现代软件开发中最重要的版本控制工具之一,它帮助开发者高效地管理项目,支持分布式协作和版本控制。无论是个人项目还是团队开发,Git 都能提供强大的功能来跟踪、管理代码变更,并保障…

系统手势导航-虚拟导航切换

问题讨论-需求场景 何为手势和物理按键、虚拟导航 Android11 开始支持了手势操作,如大家目前手机基本上都是手势操作形式;早期都是物理按键或者虚拟按键的操作。 手势导航和虚拟导航如何选择 系统层面:设置->系统->手势->手势切…

word转pdf

在线xml格式化: 在线 XML 格式化 | 菜鸟工具 Java使用FreeMarker自动生成Word文档(带图片和表单) Java使用FreeMarker自动生成Word文档(带图片和表单)_freemarker word模板-CSDN博客 将word转pdf JAVA 使用aspose…

初识java(4)

今天给大家分享一下java中内置类型定义时的一些要点,我已经整理成笔记,现在分享给大家。 整型变量: 注:在定义int变量时,所赋值不能超过int的范围; 了 intd:1234567890127411编译时报错,初值超过胃int 当你赋值的过而值大于这个变量能够保存的最大值…

Web 毕设篇-适合小白、初级入门练手的 Spring Boot Web 毕业设计项目:电影院后台管理系统(前后端源码 + 数据库 sql 脚本)

🔥博客主页: 【小扳_-CSDN博客】 ❤感谢大家点赞👍收藏⭐评论✍ 文章目录 1.0 项目介绍 2.0 用户登录功能 3.0 用户管理功能 4.0 影院管理功能 5.0 电影管理功能 6.0 影厅管理功能 7.0 电影排片管理功能 8.0 用户评论管理功能 9.0 用户购票功…

蓝桥杯嵌入式入门指南-ADC【6】

tips:可以不用开启过采样 adc读取函数 float adc_read(ADC_HandleTypeDef *hadc) {uint16_t adc_val;float adc_f;HAL_ADC_Start (hadc);adc_val HAL_ADC_GetValue(hadc);adc_f adc_val*3.3f/4096.0f;return adc_f; }setup()初始化 HAL_ADCEx_Calibration_Start(&hadc2 …

【头歌实训:递归实现斐波那契数列】

头歌实训:递归实现斐波那契数列 文章目录 任务描述相关知识递归相关知识递归举例何时使用递归定义是递归的数据结构是递归的问题的求解方法是递归的 编程要求测试说明源代码: 任务描述 本关任务:递归求解斐波那契数列。 相关知识 为了完成…

【CSP CCF记录】201803-2第13次认证 碰撞的小球

题目 样例输入1 3 10 5 4 6 8 样例输出1 7 9 9 样例输入2 10 22 30 14 12 16 6 10 2 8 20 18 4 样例输出2 6 6 8 2 4 0 4 12 10 2 思路 梳理题意,本题主要考虑三种情况: 1.小球正常运动 2.小球抵达线段两段 3.两个小球在线段某位置相撞 前两种情况很…

ML 系列:第 35 节 - 机器学习中的数据可视化

ML 系列:第 35 天 - 机器学习中的数据可视化 文章目录 一、说明二、数据可视化2.1 直方图2.2 箱线图2.3 散点图2.4 条形图2.5 线图2.6 热图 三、结尾 一、说明 描述性统计和数据可视化是理解和解释机器学习数据的基础。它们有助于总结和直观地呈现数据&#xff0c…

数字化转型背景下,高职院校计算机网络应用的革新策略

在当今信息化时代,计算机网络已经成为高职院校教育不可或缺的一部分,它不仅极大地丰富了教育资源,提高了交流的便捷性,还催生了多样化的教学模式。对于高职院校来说,加强计算机网络应用的建设不仅是顺应时代潮流的必然…

【C/C++】数据库链接入门教程:从零开始的详细指南!MySQL集成与操作

文章目录 环境配置:搭建开发环境的基础步骤2.1 安装MySQL数据库2.2 配置C/C开发环境2.3 下载并安装MySQL Connector/C 基础操作:实现C/C与MySQL的基本交互3.1 建立数据库连接3.2 执行SQL语句3.3 处理查询结果 进阶技巧:提升数据库操作效率与安…

什么是迁移学习?

一、基本概念 迁移学习(Transfer Learning)是一种机器学习方法,旨在将从一个任务中学到的/已有的知识应用到另一个相关任务中。与传统的机器学习方法不同,迁移学习不需要从头开始训练模型,而是利用(迁移)已有知识来加速…

D83【python 接口自动化学习】- pytest基础用法

day83 pytest测试用例执行顺序 学习日期:20241129 学习目标:http定义及实战 -- pytest测试用例执行顺序 学习笔记: 测试用例执行顺序 默认执行顺序使用pytest-ordering自定义顺序 pytestrequests练习 import requestsdef test_mobile()…

漫谈推理谬误——错误因果

相关文章 漫谈推理谬误——错误假设-CSDN博客文章浏览阅读736次,点赞22次,收藏3次。在日常生活中,我们会面临各种逻辑推理,有些看起来一目了然,有些非常的科学严谨,但也有很多似是而非,隐藏了陷…

如何看linux系统内核是aarch64 ,还是64-bit

要查看 Linux 系统内核是 aarch64 架构还是 64-bit 架构,可以通过以下几种方法来确认: 方法 1:使用 uname 命令 uname 命令用于显示系统信息。使用以下命令查看系统的架构: uname -m如果输出是 aarch64,说明你的系统…

Debezium Engine监听binlog实现缓存更新与业务解耦

飞书文档 解决缓存与数据源数据不一致的方案有很多, 各有优缺点; 1.0、旁路缓存策略, 直接同步更新 读取流程: 查询缓存。如果缓存命中,则直接返回结果。如果缓存未命中,则查询数据库。将数据库查询到的数据写入缓存,并设置一个…

使用命令行来刷写ELRS接收器的固件

1。使用ExpressLRS Configurator的自带编译好的python命令 "C:\Users\xxx\AppData\Local\Programs\ExpressLRS Configurator\dependencies\windows_amd64\python\python3.exe" \ "C:\Users\xxx\AppData\Roaming\ExpressLRS Configurator\firmwares\cloud\Expr…

深入理解 Docker 在 CI/CD 流程中的应用原理

Docker 和 CI/CD 是现代软件开发和运维中的两项重要技术。将 Docker 与 CI/CD 集成,可以提高软件交付速度、可靠性和可扩展性。本文将从 CI/CD 的基本概念出发,介绍 Docker 在 CI/CD 中的应用原理,展示其在各个环节中的工作流程,以…

输出1~n中能被3整除,且至少有一位数字是5的所有整数.:JAVA

链接&#xff1a;登录—专业IT笔试面试备考平台_牛客网 来源&#xff1a;牛客网 输出1~n中能被3整除&#xff0c;且至少有一位数字是5的所有整数. 输入描述: 输入一行&#xff0c;包含一个整数n。(1 < n < 100000) 输出描述: 输出所有满足条件的数&#xff0c;以换…

流量工程中的“LSP“,“RSVP“,“ISIS TE“,“OSPF TE“分别是什么?

在流量工程中&#xff0c;LSP&#xff08;Label Switched Path&#xff0c;标签交换路径&#xff09;、RSVP&#xff08;Resource Reservation Protocol&#xff0c;资源预留协议&#xff09;、IS-IS TE&#xff08;Intermediate System to Intermediate System Traffic Engine…