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

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