visual-docs-diagrams

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Visual Docs Diagrams

技术文档可视化图表

Use this skill to decide whether developer docs need visuals and to design or review those visuals for comprehension, accessibility, performance, and maintainability.

This skill is derived from Docs for Developers: An Engineer's Field Guide to Technical Writing, especially Chapter 6, "Adding visual content." The guidance is transformed and paraphrased; do not copy book prose into user outputs. Source: https://link.springer.com/book/10.1007/978-1-4842-7217-6

使用此技能判断开发者文档是否需要视觉内容，并设计或评审这些视觉内容，以确保其易理解性、可访问性、性能和可维护性。

本技能源自《Docs for Developers: An Engineer's Field Guide to Technical Writing》（《开发者文档编写：工程师技术写作实战指南》），尤其是第6章“添加视觉内容”。相关指导已进行转化和改写；请勿将书中原文复制到用户输出中。来源：https://link.springer.com/book/10.1007/978-1-4842-7217-6

Quick Start

快速入门

Load
```
guidelines.md
```
to choose the smallest useful reference set.
Define what the visual must help the reader understand or do.
Choose screenshot, diagram, flowchart, swimlane, or text-only based on the task.
Use
```
workflows/design-technical-visual.md
```
for full visual design or review.
Check accessibility, performance, placement, source files, and maintenance before finalizing.

加载
```
guidelines.md
```
以选择最精简实用的参考集。
明确该视觉内容必须帮助读者理解或完成的事项。
根据任务选择截图、图表、流程图、泳道图或纯文本形式。
使用
```
workflows/design-technical-visual.md
```
进行完整的视觉内容设计或评审。
在定稿前检查可访问性、性能、布局、源文件和维护事项。

Default Output

默认输出

When designing or reviewing visual docs, return:

Visual purpose - what the reader must understand faster or better.
Recommended visual type - screenshot, boxes-and-arrows, flowchart, swimlane, video, or no visual.
Design notes - scope, labels, annotations, contrast, placement, and format.
Accessibility and performance checks - alt text, captions, transcripts, SVG/image size, responsiveness.
Maintenance plan - source file, owner, update trigger, and review cadence.

设计或评审技术文档视觉内容时，需返回以下内容：

视觉内容用途 - 帮助读者更快或更好地理解什么内容。
推荐视觉类型 - 截图、框图、流程图、泳道图、视频或无需视觉内容。
设计说明 - 范围、标签、注释、对比度、布局和格式。
可访问性与性能检查 - 替代文本、字幕、文字记录、SVG/图片大小、响应式设计。
维护计划 - 源文件、负责人、更新触发条件和评审周期。

Need	Start Here
Understand visual types	`references/core/knowledge.md`
Apply visual rules	`references/core/knowledge.md`
See visual decision examples	`references/core/knowledge.md`
Design or review a visual	`workflows/design-technical-visual.md`
Route by task	`guidelines.md`

需求	入口文件
了解视觉内容类型	`references/core/knowledge.md`
应用视觉内容规则	`references/core/knowledge.md`
查看视觉内容决策示例	`references/core/knowledge.md`
设计或评审视觉内容	`workflows/design-technical-visual.md`
按任务选择入口	`guidelines.md`

Core Posture

核心原则

Use visuals to supplement text, not replace critical instructions.
Prefer one idea or level of detail per visual.
Treat accessibility and maintenance as part of visual design, not post-production polish.
Avoid video unless the motion itself is necessary and maintenance is realistic.

使用视觉内容补充文本，而非替代关键说明。
每个视觉内容仅聚焦一个观点或一个细节层级。
将可访问性和维护视为视觉内容设计的一部分，而非后期优化环节。
除非动态展示本身必要且维护可行，否则避免使用视频。