Submissions:2023/Save the time of the reader: improve your technical documentation through minimalist design
This submission has been noted and is pending review for WikiConference North America 2023.
Title:
- Save the time of the reader: improve your technical documentation through minimalist design
Theme:
- Technology
Type of session:
- Workshop
Abstract:
Ranganathan's fourth law of library science, "Save the time of the reader," describes how guides and frameworks that benefit library users also benefit librarians and other maintainers of information systems[1]. The laws of library science apply to technical documentation! In this workshop, participants will learn how to apply minimalist information design principles[2] to save the time of readers, while also making it easier to maintain documentation in our shared technical ecosystem.
Proposed workshop structure:
- Introduce basic information design principles from library science and instructional design.
- Teach participants how to apply minimalist design principles to improve existing technical documentation.
- Lead supported editing time and coordinate hands-on, collaborative practice revising documents on our technical wikis (mediawiki.org, wikitech.org).
After the brief introduction and instruction sections, participants will choose a technical document to improve. Then, we'll work synchronously and share ideas as we explore how minimalism can help us be strategic about revising docs to improve their usability and readability. Specifically, our revisions will focus on how to save the time of our readers (and future editors) by:
- Identifying and focusing on the reader's goals and tasks
- Creating strong "information scent"[3] through document structure and writing style
- Identifying and removing superfluous text
- Grouping information into modular, task-focused units
While the focus of this workshop will be on technical documentation, the principles are widely applicable to many types of written communication. Participants are welcome to edit any wikis or documents, but the content used for instruction and the suggested pages to edit will all be from Wikimedia technical wikis.
Author name:
E-mail address:
- tburmeister
wikimedia.org
Wikimedia username:
- TBurmeister_(WMF)
Affiliated organization(s):
- Wikimedia Foundation
Estimated time:
- 75
Special requests:
Have you presented on this topic previously? If yes, where/when?:
- I presented about writing & maintaining technical documentation as a community at the 2022 Wikimedia Hackathon [slides]. In my professional capacity as a technical writer, I've presented on information design and task-oriented documentation in various forums and settings, usually to technical audiences at engineering team events or developer summits.
Okay to livestream?
- Livestreaming is okay
If your submission is not accepted, would you be open to presenting your topic in another part of the program? (e.g. lightning talk or unconference session)
- Yes