How to tear down existing documentation and rewrite docs that actually work


We all know what it’s like to look at a series of existing documentation and think, “how did this happen?” Be it a large swath of unorganized content or a lack of a clear strategy, the complications of bad docs aren’t just a curse for documentation editors. Our readers see it, too. It leads to confused support requests and possibly a loss of customers.

When I started at Joyent, I was continuously made aware of documentation that needed help, and it felt like a nonstop firefight. Over time, I was able to quell the fires, create a content strategy, and completely redefine how our documentation works. Then all of my work was blown up a second time ‐ this time, starting from scratch with a not yet existing product. From this experience, I’ve learned it’s all about being organized and having a clear strategy.

In this talk, we’ll discuss:

  • how to get buy‐in for a documentation do‐over
  • how to pivot from rewriting docs to starting from scratch
  • content strategy (and how to write a great one)
  • empathy for our readers
  • setting easy‐to‐follow guidelines for non‐professional writers

We’ll also touch on how to prioritize and manage all of this work without additional full‐time documentation help.

  • Conference: Write the Docs Prague
  • Year: 2018

About the speaker

Alexandra White