Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Putting the (docs) Cart Before the (standards) Horse

838 views

Published on

Slides for my Write the Docs presentation, May 6, 2014 in Portland. Presentation abstract here: http://docs.writethedocs.org/2014/na/talks/#drew-jaynes-putting-the-docs-cart-before-the-standards-horse

Published in: Internet, Technology
  • Be the first to comment

Putting the (docs) Cart Before the (standards) Horse

  1. 1. Putting the (docs) Cart Before the (standards) Horse
  2. 2. THISTALK • WordPress’ approach to inline documentation • Why and how we developed a standard • Effects on the docs team after we adopted a standard • Where we are now
  3. 3. HI, I’M DREW. I work at I work on @DrewAPicture
  4. 4. BACK STORY • Very little attention was given to the “details” of inline docs • 10+ years of loosely following phpDoc 1.0 • Codex (wiki) somehow still seen as the main entry point
  5. 5. WHATTHE WHAT? • Source docs as second class • Lack of a parsed reference didn’t help
  6. 6. THE CODEX • 2300+ pages of manually-curated content • Pre-release master list • Codex sprints • Needing something better
  7. 7. HOOK DOCS • Tasked with documenting all hooks in core • Set to go where no documentarian had gone before • Needed a precedent-driven standard as a guide • Expected an influx of docs and contributors
  8. 8. REWIND • Evolution of the “Docs Team” • Established ourselves as a contributor group • Codex Survey • Informal summit at Open Help Conference • ...
  9. 9. ROADMAP
  10. 10. ROADMAP IN PROGRESS • Work began on a parser and code reference theme • 1.0 of the inline docs standard was adopted • Hook documentation began in earnest
  11. 11. DOCSTEAM EVOLVED • 3-5 sub-teams working simultaneously • Weekly chats • Weekend virtual sprints • Collaboration with other teams has raised our profile
  12. 12. WHERE ARE WE NOW? • 48 percent increase of inline docs last 3 releases • All hooks (2200+) documented • 40 new contributors over 3 releases • v1.0 of the Code Reference is live
  13. 13. TAKEAWAYS • Developing a standard proved quite beneficial • Redirect to hubs (developer, user, support) • Standard allowed for longer-term consistency • Brought the docs team to more equal footing
  14. 14. QUESTIONS? make.wordpress.org/docs

×