技术文档写作风格 - 图形

1. 图形类型1.1 架构图子类型适用场景核心元素系统架构图展示系统整体结构模块、层次、交互关系部署架构图展示物理或逻辑部署服务器、网络、存储、地域数据架构图展示数据流转与存储数据源、处理节点、存储、流向✅ 正确示例系统架构图应清晰展示接入层、业务层、数据层的模块划分及调用关系。1.2 流程图子类型适用场景规范符号业务流程图业务操作步骤开始/结束椭圆、处理矩形、判断菱形数据流程图数据流转过程数据存储开口矩形、外部实体矩形、处理圆角矩形状态转换图状态机、生命周期状态圆角矩形、转换箭头、事件标注1.3 示意图子类型适用场景特点界面截图展示操作界面标注关键操作区域去除敏感信息时序图展示交互时序对象生命线、消息箭头、激活条类图/ER图展示代码或数据模型遵循UML规范标注关键属性拓扑图展示网络或集群结构节点、连线、标签清晰1.4 数据可视化类型适用场景规范折线图趋势变化、性能曲线坐标轴标注单位图例清晰柱状图对比数据、分类统计柱宽一致间距适当饼图占比分布类别不超过6个标注百分比热力图密度、频率分布色阶清晰附色标说明2. 图形使用时机2.1 必须使用图形的场景场景原因替代方案复杂架构说明文字描述冗长且难以理解无多步骤流程纯文字步骤超过5步流程图简要文字数据对比多组数据对比表格或图表界面操作指导需精确定位操作位置截图标注性能趋势展示变化规律折线图2.2 禁止使用图形的场景场景原因替代方案简单概念说明文字即可清晰表达段落描述少量数据展示图形反而增加阅读成本表格或内联文字敏感信息展示泄露安全信息文字描述或脱敏处理动态交互说明静态图形无法表达视频或GIF3. 图形设计规范3.1 视觉规范要素规范说明配色黑白灰为主彩色不超过3种确保打印清晰色盲友好字体中文宋体/黑体英文Arial字号≥10pt标注清晰可读线条主线1.5pt辅助线0.75pt层次分明避免过细布局从左到右从上到下符合阅读习惯留白边距≥10%元素间距均匀避免拥挤3.2 内容规范要素要求正确示例错误示例标注关键元素必须标注“① 网关层”无标注读者无法识别图例符号含义必须说明“— 同步调用–→ 异步调用”线条样式无解释方向流程方向统一从上到下从左到右箭头方向混乱粒度同一图形粒度一致同为模块级或同为接口级上层模块与底层接口混杂3.3 截图规范要素要求正确示例错误示例完整性展示完整操作窗口包含标题栏、菜单栏仅截取部分区域标注红框或箭头标注操作点清晰指示按钮位置无标注或标注模糊脱敏隐藏敏感信息密码显示为******明文展示密码时效性使用当前版本界面与文档版本一致界面与版本不匹配4. 编号与标注4.1 图形编号要素规范示例编号格式“图 X-Y”X为章号Y为序号“图 3-2”位置图题下方居中图下方图题简明概括图形内容“图 3-2 系统架构图”4.2 图中标注标注类型格式用途示例数字圈注① ② ③对应正文分点说明“① 接入层”字母标注A B C对应表格或列表“区域A”箭头指引→指示流向或关联数据流向高亮框红框/黄底强调关键区域操作按钮位置✅ 正确示例图 3-2 系统架构图 ┌─────────────────────────────────────┐ │ ① 接入层Nginx │ │ 负载均衡、SSL终结 │ └──────────────┬──────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ ② 业务层微服务 │ │ 用户服务、订单服务 │ └──────────────┬──────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ ③ 数据层MySQL/Redis │ │ 主从复制、读写分离 │ └─────────────────────────────────────┘5. 与正文配合5.1 引用规范要求规范正确示例错误示例必须引用图形必须在正文中被提及“详见图 3-2”图形突兀出现引用位置图形出现在首次引用之后先写架构见图 3-2再出现图形图形在前引用在后引用格式“见图 X-Y”、“如图 X-Y 所示或见下图/上图”“系统架构见图 3-2”“点击见下图红框标注位置”“见这里的图”相对引用图形紧邻时可用下图/上图“配置界面见下图”图形距离较远时用下图分点说明对图中标注逐点解释“① 接入层负责…”仅写见图无解读5.2 引用方式选择场景推荐引用方式示例图形与引用同页且紧邻“见下图/上图”“系统架构见下图”图形与引用跨段落或跨页“见图 X-Y”“系统架构见图 3-2”正式技术文档“如图 X-Y 所示”“系统架构如图 3-2 所示”多图连续引用混合使用“见图 3-2详细配置步骤见下图”5.3 内容互补原则正文职责图形职责正文为主说明设计思路、关键决策、注意事项展示结构、流程、关系图形为辅不重复描述图形已清晰表达的内容不承载详细参数和配置相互印证文字描述与图形展示一致图形标注与正文术语一致✅ 正确示例使用下图正文 系统采用分层架构设计各层职责如下 - 接入层负责请求分发和SSL终结 - 业务层处理核心业务逻辑 - 数据层管理持久化存储 系统架构见下图 [图 3-2 系统架构图] 如上图所示接入层部署Nginx集群实现负载均衡业务层采用微服务架构支持独立扩容。✅ 正确示例使用图 X-Y正文 系统采用分层架构设计见图 3-2。接入层负责请求分发和SSL终结业务层处理核心业务逻辑数据层管理持久化存储。各层间通过RESTful API通信避免直接依赖。 图 3-2 系统架构图 [图形展示三层结构及调用关系] 如图 3-2 所示接入层部署Nginx集群实现负载均衡业务层采用微服务架构支持独立扩容数据层使用MySQL主从复制保障高可用。5.4 位置安排规范要求说明就近原则图形紧跟首次引用段落不宜跨页或跨章节独立成块图形前后各空一行与正文区分避免拆分图形尽量在同一页大图可放附录或折页清晰度分辨率≥150dpi矢量图优先放大不失真6. 规范速查表类别核心规范检查要点图形类型架构图、流程图、示意图、数据可视化按需选择类型是否匹配内容是否滥用或缺失使用时机复杂架构、多步骤流程、数据对比、界面操作必须用简单概念、少量数据、敏感信息禁用是否该用图形是否可用文字替代设计规范配色≤3种、字体≥10pt、线条分明、布局合理、留白适当视觉是否清晰标注是否完整编号标注图 X-Y格式、图题简明、图中标注清晰编号格式是否正确标注是否对应正文与正文配合必须引用、位置就近、内容互补、分点解读紧邻时用下图/上图远离时用图 X-Y正文是否提及引用方式是否恰当是否解读关键元素