Skip to content
Presentation for Write The Docs Prague 2018
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
assets
examples
README.md
keynote_how-to-tear-down-your-docs_final.key
ppt_how-to-tear-down-your-docs_final.pptx
slides_how-to-tear-down-your-docs.pdf

README.md

How to tear down your documentation

(And rewrite docs that actually work)

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.

Talk abstract

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.

Real talk abstract

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.

Who am I?

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.

Additional Resources

Photography and iconography

You can’t perform that action at this time.