47 lines
3.6 KiB
Markdown
47 lines
3.6 KiB
Markdown
# Research synthesis: enterprise technical-document diagrams
|
|
|
|
## Observed enterprise practice
|
|
|
|
- AWS publishes official architecture icons and explicitly supports common drawing tools including diagrams.net/draw.io and Figma. Its guidance frames diagrams as communication of design, deployment, and topology.
|
|
- Microsoft Azure's Well-Architected guidance emphasizes selecting and layering diagram types by message, audience, and lifecycle; directional arrows; clear labels; consistency; legends; accessibility; progressive disclosure; and version-controlled source files. Azure also distributes official SVG architecture icons and asks authors to keep product names with icons and avoid distortion.
|
|
- Google Cloud distributes official product icons in SVG and PNG for architecture diagrams and documentation.
|
|
- IBM Cloud identifies draw.io as an approved design tool and also publishes SVG and presentation assets.
|
|
- Oracle Cloud publishes architecture toolkits for draw.io, Visio, and PowerPoint and exposes editable DRAWIO plus SVG versions for reference architectures.
|
|
- GitHub renders Mermaid in Markdown and supports additional structured visual formats. GitLab supports Mermaid, PlantUML, Kroki, and diagrams.net content in documentation/wiki workflows.
|
|
|
|
The shared pattern is not a single winning authoring format. It is a **source-preserving pipeline**: official semantics/iconography, editable source, and a stable publication artifact.
|
|
|
|
## Why the harness uses an intermediate representation
|
|
|
|
Direct generation into draw.io XML, Mermaid, or SVG couples semantic reasoning to tool syntax and makes factual review difficult. VizSpec creates a review boundary:
|
|
|
|
1. document context and evidence;
|
|
2. semantic intent and relationships;
|
|
3. deterministic layout/rendering;
|
|
4. visual and accessibility quality gates.
|
|
|
|
This supports multiple agent hosts and multiple output ecosystems without allowing format-specific details to become undocumented facts.
|
|
|
|
## Relevant research principles
|
|
|
|
- The “Physics of Notations” framework argues that cognitively effective visual notations require semantic clarity, perceptual discriminability, semantic transparency, manageable visual complexity, cognitive integration, and related principles.
|
|
- Multimedia-learning research supports coherence (remove irrelevant material), signaling (make organization and essentials visible), and spatial contiguity (place words near the graphics they explain).
|
|
- Graph-drawing research repeatedly treats crossings, bends, edge length, and layout regularity as major readability variables.
|
|
- W3C accessibility guidance requires text alternatives for non-text content and sufficient contrast for meaningful non-text visual information. Complex diagrams need structured descriptions beyond a short alt phrase.
|
|
|
|
## Source set used for the design
|
|
|
|
Primary vendor/documentation sources reviewed:
|
|
|
|
- AWS Architecture Icons and Architecture Center
|
|
- Microsoft Azure Well-Architected Framework: Architecture design diagrams; Azure Architecture Icons
|
|
- Google Cloud Architecture Center and Cloud icon library
|
|
- IBM Cloud design resources
|
|
- Oracle Cloud Infrastructure architecture diagram toolkits and reference architectures
|
|
- GitHub Docs: Creating diagrams in Markdown
|
|
- GitLab Docs: Mermaid, PlantUML, Kroki, and diagrams.net integrations
|
|
- Mermaid, D2, Graphviz, Structurizr/C4, diagrams.net, and Excalidraw official documentation
|
|
- W3C Web Content Accessibility Guidelines and WAI complex-images guidance
|
|
|
|
The executable policy in this repository is intentionally stricter than any single source: it combines evidence grounding, accessible output, source preservation, and agent-host portability.
|