Draw the Docs - Alicja Raszkowska

A non-technical-writer engineer built a practical, repeatable way to use drawings in day-to-day work—then turned that into a documentation-friendly workflow using Mermaid-style diagrams. The core finding is simple: when diagrams are easy to create, version, and reuse, teams stop treating “visual communication” as a special skill and start using it to debug, align, and explain complex systems.

The talk starts with a personal problem: learning to draw felt intimidating, especially for someone who isn’t a native English speaker and isn’t trained as a technical writer. Drawing became a way to think—simplifying concepts into chunks, adding humor, and making hard-to-remember details stick. That practice expanded from personal learning (like Haskell) into work communication. Diagrams and sketches helped colleagues understand infrastructure and APIs faster, and they made documentation feel less daunting. The speaker also leaned on a broader idea from sketchnoting: you don’t need “art skills,” just a small set of shapes and practice to communicate ideas.

To make drawing sustainable at work, the speaker framed it as job-relevant, not a hobby. Engineers already use whiteboards and diagrams for debugging, retrospectives, and shared planning, and technical writers rely on diagrams to clarify what subject-matter experts describe. Sales teams also sketch quickly to explain systems to customers. The gap wasn’t that diagrams didn’t exist—it was that diagram creation and refinement often required manual re-drafting, designer handoffs, and repeated effort as products changed.

From there came a workflow goal: enable anyone to generate diagrams that are reusable, extendable, and automatable, without forcing teams to abandon existing design processes. The speaker explored tool choices but argued against building a separate product from scratch unless it directly serves core business value. Instead, the approach became a proof-of-concept built around Mermaid: an open-source abstraction of d3.js that generates diagrams from Markdown-like syntax, supports an API in a headless browser environment, and can output SVG for downstream tooling.

The proof-of-concept demonstrated a “visual language” layer. By using HTML/CSS to map icons and styling, the same underlying diagram logic could switch between whimsical internal icons (for engagement) and more serious AWS-style visuals (for professional documentation). Diagrams could be saved as text, version-controlled, shared via encoded links, and edited collaboratively—turning understanding into something others can quickly review and correct.

The workflow wasn’t perfect. Generating SVG with custom CSS didn’t integrate cleanly with designer tools like Sketch, and the system still needed brand-compliant styling and maintenance. Upstream library limitations also affected CLI SVG generation. Still, the results were immediate: engineers used the tool to clarify system connections during debugging, and faster shared understanding led to quicker fixes when misunderstandings surfaced (for example, confusion between Lambda and Lambda@Edge).

The final message was iterative: treat visual documentation like a living workflow—refactor, repeat, and improve—so teams can communicate more effectively without relying on rare drawing talent. The call to action: “go and draw your Docs,” starting with simple sketches and evolving toward reusable visual systems.