How to tear down existing documentation and rewrite docs that actually work¶
Description
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
