putting the (docs) cart before the (standards) horse
DESCRIPTION
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-horseTRANSCRIPT
Putting the (docs) Cart Before the (standards) Horse
THIS TALK
• 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
HI, I’M DREW.
I work at I work on
@DrewAPicture
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
WHAT THE WHAT?
• Source docs as second class
• Lack of a parsed reference didn’t help
THE CODEX
• 2300+ pages of manually-curated content
• Pre-release master list
• Codex sprints
• Needing something better
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
REWIND
• Evolution of the “Docs Team”
• Established ourselves as a contributor group
• Codex Survey
• Informal summit at Open Help Conference
• ...
ROADMAP
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
DOCS TEAM EVOLVED
• 3-5 sub-teams working simultaneously
• Weekly chats
• Weekend virtual sprints
• Collaboration with other teams has raised our profile
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
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
QUESTIONS?
make.wordpress.org/docs