Putting the (Docs) Cart Before the (Standards) Horse


When people think of documentation standards, I'd wager the first thing that comes to mind is probably something like "uniformity", or "best practice", or "one voice". And in consideration of that, most people probably also view standards as the de facto "starting place" for all the things to come after.

So what happens when you turn that idea on its head, that is to say, 'write the documentation first, and develop standards later'?

In the WordPress open source project, we did that. We developed an inline documentation standard using 10 years of contributions as a starting place.

This talk will cover some of the challenges we overcame to develop a new standard using legacy documentation. Also:

  • Tools we used to assess our existing documentation "style".
  • How our new standards have been applied in practice.
  • How having a standard has allowed the docs team to rise to equal footing.