Seeing is believing
By Andrea Kao

This talk explores the challenges and shortcomings of written documentation in contrast to the capabilities of visual communication. We’ll discuss reasons why diagrams, flow charts, or drawings may be more effective than words in the context of knowledge-sharing. We’ll also discuss real-life use cases, ideas from the Write the Docs community, and concepts from media studies and neuroscience.

Documentation is critical to the long-term health of any software system. The more complex, nay, the more convoluted and messy the system, the more likely it is better served with visual documentation than it is with written documentation. Visual documentation can take varied forms: from sketches or cartoons that narrate a single concept or describe a single workflow, to flow charts that detail multiple, tangled threads of business logic.

In this talk, we’ll discuss the specific advantages of using imagery to convey technical messages. For example, imagery can bypass or cut through the obstacles of language barriers and limited attentional bandwidth. Furthermore, the usage of drawings or diagrams can be an effective technique for combating the inertia and lethargic feelings that can accompany the documentation process itself.

I’ll give examples from my own experience documenting both legacy projects and modern web applications. In terms of tooling, I'll explain how my team and I have familiarized ourselves with Sphinx and rST and how we make decisions to implement new tools (e.g., Mermaid.js).

This talk references discussions from the Write the Docs community (for example, the usage of rST versus Markdown). It draws specific inspiration from Alicja Raszkowksa’s Draw the Docs presentation and community heroes like Julia Evans (among others). It will also quote thinkers in media studies (e.g., Marshall McLuhan, Susan Sontag), as well as explore concepts from neuroscience (e.g., memory and relaxed attention).

Andrea Kao

I write software documentation and organize meetups for the open-source community in Los Angeles.

In alternative universes, I also write for myself, I write code, and I play music.

I'm a California native and a child of immigrants.