In this repository, you will find my presentation for Write The Docs Prague 2018. This includes a PDF version of the slides, Keynote, Microsoft PowerPoint, and visual assets.
Watch a recording of the live talk on YouTube.
Find me on Twitter and tweet during the presentation with #writethedocs.
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.
While in the middle of my overhaul, my work was blown up a second time and my project was put on hold. From these challenges, 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.
The big divergence is that I'm going to spend most of the time talking about how to write a proposal to convince your manager to let you tear down your docs. Useful stuff, I hope.
See and use this example outline.
My name is Alexandra White, and at the time of this talk, I was a technical writer for Joyent. Prior to that, I was a web developer for a U.S. television station, WNET. Throughout my career I've been an advocate for code comments, useful READMEs, and reusable documentation.
- See my work. It's mostly web development projects, but there's also some writing.
- Let's be Twitter friends. People should be nicer on Twitter. We can be those people.
