Self-Documenting Coders: A Writing Workshop for Devs

By Heidi Waterhouse

Elevator Pitch

Being able to use language effectively saves so much coding trauma. You should learn to file good bug reports, write up problems, and describe what you’re doing. I’ll teach you in less than half a day!

Description

What is a documentation structure, and why does it matter to developers? Lots of developers get asked to write their own documentation, especially internal documentation and onboarding. In theory, this is good because they know the problems they are writing about and don’t need to spend time explaining them. In practice, developers avoid this work because they don’t have a good idea of how to start and can’t evaluate whether they have succeeded.

This workshop is designed to teach you a few basic theories of technical documentation, such as task-based topics, reusable content, and writing for an audience. After the overview, you’ll learn techniques for writing bug reports, error messages, and onboarding instructions in a tool-agnostic, repeatable way. You’ll leave this workshop with a handful of techniques, templates, and tests that will improve your team’s communication and your life as a developer.

  • What is structure?
  • What do I really need to know?
  • How to write an error message
  • How to write a bug report
  • What is transparent to writers?
  • How do you interact with the team around building stuff.

Technical documentation, then and now

  • Linear writing
  • Task-based writing
  • Searchable writing

Tech writing tools

  • Making words ** Research basics ** Writing basics ** Using templates to write
  • Organizing words ** Every page is page one/search-first writing ** Indexing and search ** Sorting topics into buckets
  • Distributing words ** Static sites ** Hosted sites ** Paper-ish things

Docs have to be

  • True
  • Timely
  • Testable
  • (Tuned)

Documentation components

  • Why are we reading this document?
  • Prerequisites
  • How do I do this task?
  • Test - How do I know it worked?
  • Reference
  • Optional: architecture, further resources, use cases, etc