Keep Calm and Mind the Docs
By Andrea Kao

Documentation is critical to the long-term health of any software system. The more complex the system, the more likely it is better served with visual tools than it is with the written word. And visual communication can take varied forms: from sketches, cartoons, or animations that narrate a single concept or describe a single workflow, to diagrams that detail multiple, tangled threads of business logic.

In this talk, we’ll discuss the advantages of using imagery to convey technical messages. For one thing, imagery can bypass or cut through the obstacles of language barriers, limited attentional bandwidth, and limited memory. Furthermore, the usage of drawings or diagrams can be an effective technique for combating the inertia and lethargic feelings that can accompany the software development process itself. I’ll give examples from my own experience as a technical writer and as a human being.

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 studies in neuroscience and mindfulness. We'll talk about the emotional labor that's inherent in creating and reading documentation, and we'll talk about how the documentation process can become more humane.