Submissions:2023/Save the time of the reader: improve your technical documentation through minimalist design

From WikiConference North America
Revision as of 15:45, 20 June 2023 by TBurmeister (talk | contribs) (Create page)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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:

  1. Introduce basic information design principles from library science and instructional design.
  2. Teach participants how to apply minimalist design principles to improve existing technical documentation.
  3. 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:

Tricia Burmeister

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