如何写一份优质技术文档
作者简介:
本文作者拥有区块链创新专利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、阅读与学习:优秀的技术文章
相关文章:
如何写一份优质技术文档
作者简介: 本文作者拥有区块链创新专利30,是元宇宙标准化工作组成员、香港web3标准工作组成员,参与编写《数据资产确权与交易安全评价标准》、《链接元宇宙:应用与实践》、《香港Web3.0标准化白皮书》等标准,下面提供…...
ML 系列:第 35 节 - 机器学习中的数据可视化
ML 系列:第 35 天 - 机器学习中的数据可视化 文章目录 一、说明二、数据可视化2.1 直方图2.2 箱线图2.3 散点图2.4 条形图2.5 线图2.6 热图 三、结尾 一、说明 描述性统计和数据可视化是理解和解释机器学习数据的基础。它们有助于总结和直观地呈现数据,…...
存储服务器一般做是做什么阵列?详细列举一下
存储服务器通常使用 RAID(Redundant Array of Independent Disks) 阵列技术来管理磁盘,以提高数据的性能、可靠性和可用性。所选择的 RAID 类型取决于存储服务器的具体用途和需求,比如性能要求、容量需求、容错能力等。 以下是存…...
uniapp使用扩展组件uni-data-select出现的问题汇总
前言 不知道大家有没有学习过我的这门课程那,《uniCloud云开发Vue3版本官方推荐用法》,这么课程已经得到了官方推荐,想要快速上手unicloud的小伙伴们,可以学习一下这么课程哦,不要忘了给一键三连呀。 在录制这门课程…...
pdf.js 预览pdf的时候发票数据缺失显示不全:字体加载出错(缺失)导致部分缺失
首先,排除后端返回的PDF文件流是没有问题的: 但是在vue项目中是这样的: 明显是显示不全,F12查看报错信息,有以下警告: pdf.js:2153 Warning: Error during font loading: The CMap “baseUrl” paramet…...
【设计模式】【结构型模式(Structural Patterns)】之外观模式(Facade Pattern)
1. 设计模式原理说明 外观模式(Facade Pattern) 是一种结构型设计模式,它提供了一个统一的接口,用来访问子系统中的一群接口。外观模式定义了一个高层接口,这个接口使得这一子系统更加容易使用。通过隐藏子系统的复杂…...
Redis使用场景-缓存-缓存穿透
前言 之前在针对实习面试的博文中讲到Redis在实际开发中的生产问题,其中缓存穿透、击穿、雪崩在面试中问的最频繁,本文加了图解,希望帮助你更直观的了解缓存穿透😀 (放出之前写的针对实习面试的关于Redis生产问题的博…...
介绍 Apache Spark 的基本概念和在大数据分析中的应用
Apache Spark 是一个开源的大数据处理框架,它提供了快速、通用、可扩展的数据处理能力。Spark可以处理大规模数据集,并且在内存中进行数据操作,从而实现高速的数据处理和分析。 Spark的核心概念是弹性分布式数据集(Resilient Dis…...
OpenCPN-插件之Dashboard Tactics
1:相关链接Dashboard Tactics :: OpenCPN Dashboard Tactics Plugin rgleason/dashboard_tactics_pi: OpenCPN dashboard built-in plugin merger with external tactics_pi plugin NMEAconverter :: OpenCPN 2:显示样式 3:代码 这个插件…...
【LeetCode面试150】——20有效的括号
博客昵称:沈小农学编程 作者简介:一名在读硕士,定期更新相关算法面试题,欢迎关注小弟! PS:哈喽!各位CSDN的uu们,我是你的小弟沈小农,希望我的文章能帮助到你。欢迎大家在…...
JWT介绍和结合springboot项目实践(登录、注销授权认证管理)
目录 一、JWT介绍(一)基本介绍(二)jwt有哪些库1、jjwt(Java JWT)2、nimbus - jwt - jwt - api 和 nimbus - jwt - jwt - impl3、spring - security - jwt(已弃用,但在旧项目中有参考…...
Linux 下安装 Golang环境
Linux 下安装 Golang 获取Golang下载地址 安装 进入终端,登入root来到应用安装目录使用 wget 下载解压文件配置环境变量查看golang版本,测试是否配置成功GO设置代理环境变量 本篇教程 以 centos7 为环境基础 不使用软件包管理器安装,原因&am…...
「Mac畅玩鸿蒙与硬件36」UI互动应用篇13 - 数字滚动抽奖器
本篇将带你实现一个简单的数字滚动抽奖器。用户点击按钮后,屏幕上的数字会以滚动动画的形式随机变动,最终显示一个抽奖数字。这个项目展示了如何结合定时器、状态管理和动画实现一个有趣的互动应用。 关键词 UI互动应用数字滚动动画效果状态管理用户交…...
安装使用Ubuntu18.04超级大全集最初版(anaconda,pycharm,代理,c/c++环境)
本文介绍ubuntu1804中我目前用到的环境的完整配置,包括ubuntu安装软件,更新环境变量等都有涉及。图片非常多,能给的连接和材料都给了。希望能帮助到新同学。 目录 目录 目录 环境及镜像文件 安装Ubuntu 编辑 开机之后 编辑 更新…...
Redis设计与实现第16章 -- Sentinel 总结1(初始化、主从服务器获取信息、发送信息、接收信息)
Sentinel是Redis的高可用解决方案:由一个或多个Sentinel实例组成的Sentinel系统可以监视任意多个主服务器,以及这些主服务器属下的所有从服务器,被监视的主服务器进入下线状态时,自动将下线主服务器属下的某个从服务器升级为新的主…...
ChatGPT科研应用、论文写作、课题申报、数据分析与AI绘图
随着人工智能技术的飞速发展,ChatGPT等先进语言模型正深刻改变着科研工作的面貌。从科研灵感的激发、论文的高效撰写,到课题的成功申报,乃至复杂数据的深度分析与可视化呈现,AI技术均展现出前所未有的潜力。其实众多科研前沿工作者…...
OceanBase数据库系列之:基于docker快速安装OceanBase数据库,基于linux服务器快速部署OceanBase数据库
OceanBase数据库系列之:基于docker快速安装OceanBase数据库,基于linux服务器快速部署OceanBase数据库 一、docker快速安装OceanBase数据库下载OceanBase数据库镜像查看镜像启动OceanBase数据库查看OceanBase数据库是否启动成功 二、基于linux部署OceanBa…...
无星的微前端之旅(四)——qiankun线上服务代理到本地
这个方式其实是我在上家公司的时候体验过,觉得确实很有意思。 所以这里来逆推一下实现方式。 解决了什么痛点 1.开发一个模块,需要启动2-3个项目 在微前端的开发过程中,如果我们要在主应用中看效果,我们至少需要启动一个主应用&am…...
鸿蒙进阶篇-Stage模型、UIAbility
“在科技的浪潮中,鸿蒙操作系统宛如一颗璀璨的新星,引领着创新的方向。作为鸿蒙开天组,今天我们将一同踏上鸿蒙基础的探索之旅,为您揭开这一神奇系统的神秘面纱。” 各位小伙伴们我们又见面了,我就是鸿蒙开天组,下面让我们进入今…...
快速上手:如何开发一个实用的 Edge 插件
在日常浏览网页时,背景图片能够显著提升网页的视觉体验。如果你也想为自己的浏览器页面添加个性化背景图片,并希望背景图片设置能够持久保存,本文将介绍如何通过开发一个自定义Edge插件来实现这一功能。我们将涵盖保存背景设置到插件选项页&a…...
java缓存技术点介绍
1. 缓存(Cache): • 缓存是指用于存储数据的临时存储区域,以便快速访问。在Java中,缓存通常用于存储频繁访问的对象、结果集或其他数据。 2. 缓存命中率(Cache Hit Ratio): • 缓存命…...
【单片机毕业设计12-基于stm32c8t6的智能称重系统设计】
【单片机毕业设计12-基于stm32c8t6的智能称重系统设计】 前言一、功能介绍二、硬件部分三、软件部分总结 前言 🔥这里是小殷学长,单片机毕业设计篇12-基于stm32c8t6的智能称重系统设计 🧿创作不易,拒绝白嫖可私 一、功能介绍 ----…...
音视频流媒体直播/点播系统EasyDSS互联网视频云平台介绍
随着互联网技术的飞速发展,音视频流媒体直播已成为现代社会信息传递与娱乐消费的重要组成部分。在这样的背景下,EasyDSS互联网视频云平台应运而生,它以高效、稳定、便捷的特性,为音视频流媒体直播领域带来了全新的解决方案。 1、产…...
3dtile平移子模型以及修改 3D Tiles 模型的模型矩阵z平移
第一段代码:应用平移变换到子模型 这段代码的目的是获取子模型的变换矩阵,并将其平移 10 个单位。 if (submodel) {// 获取当前子模型的变换矩阵let transform submodel.transform// 创建一个向上的平移矩阵,平移 10 个单位let translation…...
JavaScript中类数组对象及其与数组的关系
JavaScript中类数组对象及其与数组的关系 1. 什么是类数组对象? 类数组对象是指那些具有 length 属性且可以通过非负整数索引访问元素的对象。虽然这些对象看起来像数组,但它们并不具备真正数组的所有特性,例如没有继承 Array.prototype 上…...
【机器学习】机器学习学习笔记 - 监督学习 - 逻辑回归分类朴素贝叶斯分类支持向量机 SVM (可分类、可回归) - 04
逻辑回归分类 import numpy as np from sklearn import linear_modelX np.array([[4, 7], [3.5, 8], [3.1, 6.2], [0.5, 1], [1, 2], [1.2, 1.9], [6, 2], [5.7, 1.5], [5.4, 2.2]]) y np.array([0, 0, 0, 1, 1, 1, 2, 2, 2])# 逻辑回归分类器 # solver:求解器&a…...
Python脚本文件开头两行#!/usr/bin/python和# -*- coding: utf-8 -*-的作用
Linux环境下,Python脚本代码文件,比如test.py,文件的第一行一般要指定解释器,使用Linux的Shebang的形式指定,第二行一般指定编码格式。 首行指定解释器工具,使用方式如下: # 第1种方式&#x…...
使用PyQt5开发一个GUI程序的实例演示
一、安装Python 下载安装到这个目录 G:\Python38-32 安装完成有这些工具,后面备用: G:\Python38-32\Scripts\pyrcc5.exe G:\Python38-32\Scripts\pyuic5.exe 二、PyQt环境配置 pip install PyQt5 pip install pyqt5-tools 建议使用国内源,…...
3d扫描建模产品开发-三维扫描检测蓝光检测
现当下,汽车制造、航空航天,还是消费电子、医疗器械,三维扫描检测与蓝光技术正以前所未有的精度和效率,推动着产品从概念到实物的快速转化。 三维扫描技术,简而言之,就是通过激光、结构光(如蓝…...
多线程——01
1. 进程/任务 process/task 进程是操作系统对一个正在运行的程序的一种抽象,换言之,可以把进程看做程序的一次运行过程 每个进程想要执行,都需要消耗一定的系统资源(硬件资源) 1)进程在系统中的作用 a…...
Makefile中-D选项定义预编译处理宏
1.简单示例假设我们有一个简单的 C 程序main.c,内容如下: #include <stdio.h> #ifdef DEBUGvoid print_debug_info() {printf("This is debug information.\n");} #elsevoid print_debug_info() {} #endif int main() {print_debug_info();printf("Prog…...
NAPI杂记
NAPI和tasklet区别:NAPI是利用的软中断NET_RX_SOFTIRQ实现, tasklet是利用TASKLET_SOFTIRQ实现 另外文章说NAPI主要是采用轮询,可以减少中断触发次数。do_softirq里面是开中断执行的啊? 中断处理函数关闭中断开始处理。如果此时…...
006 MATLAB编程基础
01 M文件 MATLAB输入命令有两种方法: 一是在MATLAB主窗口逐行输入命令,每个命令之间用分号或逗号分隔,每行可包含多个命令。 二是将命令组织成一个命令语句文集,使用扩展名“.m”,称为M文件。它由一系列的命令和语句…...
使用Alpine镜像作为基础镜像的Dockerfile配置
配置阿里 apk源: /etc/apk/repositories: https://mirrors.aliyun.com/alpine/v3.13/main alpine-v3.13-community安装包下载_开源镜像站-阿里云 或者使用命令 sed -i sdl-cdn.alpinelinux.orgmirrors.aliyun.comg /etc/apk/repositories dockerfil…...
RAG (Retrieval Augmented Generation) 检索增强和生成
1 RAG技术简介 1.1 RAG技术概述 RAG(Retrieval Augmented Generation) 是一种结合了检索(Retrieval)和生成(Generation)的技术,旨在通过利用外部知识库来增强大型语言模型(LLMs&am…...
Figma入门-约束与对齐
Figma入门-约束与对齐 前言 在之前的工作中,大家的原型图都是使用 Axure 制作的,印象中 Figma 一直是个专业设计软件。 最近,很多产品朋友告诉我,很多原型图都开始用Figma制作了,并且很多组件都是内置的,…...
039集——渐变色之:CAD中画彩虹()(CAD—C#二次开发入门)
(来左边儿 跟我一起画个龙,在你右边儿 画一道彩虹 ~~~~~~~~~~~ ) 效果如下: namespace AcTools {public class Class1{public Wform.Timer timer;//定时器需建在类下面public static DateTime startTime;[CommandM…...
MTK主板_小型联发科安卓主板_行业智能终端主板基于联发科方案
MTK安卓主板是一款小巧而高效的科技产品,其尺寸仅为43.4mm x 57.6mm。采用了先进的联发科12nm制程工艺,这款主板搭载四核或八核64位A53架构的CPU,主频高达2.0GHz,不但保证了出色的计算能力,还实现了超低功耗的特点。系…...
Arrays.copyOfRange(),System.arraycopy() 数组复制,数组扩容
Arrays.copyOfRange() 当需要将数组中的 长度扩容时, 数组复制 使用 需要用到Arrays 类提供的的 参数解析 * param original the array from which a range is to be copied * param from the initial index of the range to be copied, inclusive * param to the final ind…...
Docker for Everyone Plus——No Enough Privilege
直接告诉我们flag在/flag中,访问第一小题: sudo -l查看允许提权执行的命令: 发现有image load命令 题目指明了有rz命令,可以用ZMODEM接收文件,看到一些write up说可以用XShell、MobaXterm、Tabby Terminal等软件连接上…...
ElasticSearch学习笔记把:Springboot整合ES(二)
一、前言 上一篇文章中我们学习了ES中的Term级别的查询,包括 term、terms、terms_set、rang等,今天我们使用Java代码实现一遍上述的查询。 二、项目依赖 POM <?xml version"1.0" encoding"UTF-8"?> <project xmlns&q…...
Linux系统之iotop命令的基本使用
Linux系统之iotop命令的基本使用 一、iotop命令介绍二、iotop命令的使用帮助2.1 安装iotop2.2 iotop命令help帮助信息2.3 iotop命令选项解释 三、 iotop命令的基本使用四、iotop使用注意事项 一、iotop命令介绍 iotop 是一个类似于 top 的命令行工具,但它专注于显示…...
根据合约地址判断合约协议的方法
判断合约协议之前,需要了解一下什么是ERC165协议: ERC165 是以太坊中用于标准化接口检测的协议,由 Fabian Vogelsteller 在 2018 年创建 ,其核心内容主要包括以下方面: 接口定义 单一函数接口:ERC165 协议…...
什么是sfp,onu,为什么PON(俗称“光猫”)模块使用SC光纤接口
在现代网络设备中,我们经常会看到SFP或SFP接口的身影,这些接口有时被简称为光口,但这个称呼并不严谨。有些厂商则称之为多功能口或多用途口,然而这对于不了解的人来说可能还是一头雾水。SFP,即Small Form-Factor Plugg…...
链表?->?(以尾插法说明,附头插法)
这篇文章做一些关于初学链表的一些问题的解答。 我知道有些朋友只是需要一份完整的关于链表的代码,我会附在后面,大家直接划到最后就好。 一、创建链表 (1 相信所有搜索过链表创建的朋友都看过这样一行: struct Line* head (struct Line…...
11.29周五F34-Day10打卡
文章目录 1. 问问他能不能来。解析答案:【解析答案分析】【对比分析】【拓展内容】2. 问题是他能不能做。解析答案:【解析答案分析】3. 问题是我们能否联系得上她。(什么关系?动作 or 描述?)解析答案:【解析答案分析】【对比分析】4. 我们在讨论是否要开一个会。解析答案:…...
【项目日记】仿mudou的高并发服务器 --- 实现HTTP服务器
对于生命,你不妨大胆一点, 因为我们始终要失去它。 --- 尼采 --- ✨✨✨项目地址在这里 ✨✨✨ ✨✨✨https://gitee.com/penggli_2_0/TcpServer✨✨✨ 仿mudou的高并发服务器 1 前言2 Util工具类3 HTTP协议3.1 HTTP请求3.2 HTTP应答 4 上下文解析模块…...
【SpringBoot问题】IDEA中用Service窗口展示所有服务及端口的办法
1、调出Service窗口 打开View→Tool Windows→Service,即可显示。 2、正常情况应该已经出现SpringBoot,如下图请继续第三步 3、配置Service窗口的项目启动类型。微服务一般是Springboot类型。所以这里需要选择一下。 点击最后一个号,点击Ru…...
Ubuntu20.04运行LARVIO
文章目录 1.运行 Toyish 示例程序2.运行 ROS Nodelet参考 1.运行 Toyish 示例程序 LARVIO 提供了一个简化的toyish示例程序,适合快速验证和测试。 编译项目 进入 build 文件夹并通过 CMake 编译项目: mkdir build cd build cmake -D CMAKE_BUILD_TYPER…...
数字化转型背景下,高职院校计算机网络应用的革新策略
在当今信息化时代,计算机网络已经成为高职院校教育不可或缺的一部分,它不仅极大地丰富了教育资源,提高了交流的便捷性,还催生了多样化的教学模式。对于高职院校来说,加强计算机网络应用的建设不仅是顺应时代潮流的必然…...