CORE DOCS:
SENTENCING WORDPRESS
TO 11-YEARS-TO-LIFE
WHAT IS CORE DOCUMENTATION?
• The Codex
• Inline docs/commenting
• The code itself
• Docs as “developer experience”
CINCINNATI 2013
CINCINNATI MEETUP
• Survey analysis
• Brainstorming
• Roadmap
CODEX SURVEY
• Incomplete, outdated, wrong
• Tutorials and examples
• StackExchange/StackOverflow
LIKE DON’T LIKE
CODEX != SUSTAINABLE
ROADMAP
http://make.wordpress.org/docs/2013/06/19/docs-sprint-results-and-roadmap/
ROADMAP
• Constrain the scope of docs to the core project
• Reduce and refine
• Separate developer from user documentation
1. DEVELOPER HUB
1. DEVELOPER HUB
• Code Reference
• Standards/Parser
• Hook Docs
• Code Reference Theme
CODE REFERENCE
EXAMPLE EXAMPLE
+
2. HANDBOOKS
2. HANDBOOKS
• Plugin, theme developers
• Polyglots, users, etc.
• Rewrite, focus the content
• Reorganize
3. SUPPORT HUB
3. SUPPORT HUB
• Getting Started, task-based guides
• Knowledge base
• Identifying cross-over content
4. DISMANTLING THE CODEX
4. DISMANTLING THE CODEX
• Migrate remaining content to inline docs
and explanations
• Massive 301 redirect
WHAT’S NEXT
SHINY THINGS
• Examples voting
• Explanations
• Hook aliases
• Documenting default arguments
SHINY IDEAS
• Adopt the JSDoc3 standard
• Parsed JavaScript docs
• Extended references
• and …
Drew Jaynes | @DrewAPicture
Slides: http://drewf.us/wcnyc
Core Docs: Sentencing WordPress to 11-years-to-life
Core Docs: Sentencing WordPress to 11-years-to-life
Upcoming SlideShare
Loading in …5
×

Core Docs: Sentencing WordPress to 11-years-to-life

4,717 views

Published on

Core docs extend far beyond maintaining dated Codex pages and writing inline comments. In fact, even the way core code is written is a contributor to core documentation. And in all the ways we contribute docs, we need to ensure they stand the test of time.

This talk takes a stroll through the docs roadmap devised Summer 2013 and how that’s progressing. We’ll examine the diminished role the Codex will take going forward, as well as highlight some exciting initiatives coming into the fold — including the handbooks, code reference, and more.

Published in: Education
  • Be the first to comment

Core Docs: Sentencing WordPress to 11-years-to-life

  1. 1. CORE DOCS: SENTENCING WORDPRESS TO 11-YEARS-TO-LIFE
  2. 2. WHAT IS CORE DOCUMENTATION? • The Codex • Inline docs/commenting • The code itself • Docs as “developer experience”
  3. 3. CINCINNATI 2013
  4. 4. CINCINNATI MEETUP • Survey analysis • Brainstorming • Roadmap
  5. 5. CODEX SURVEY • Incomplete, outdated, wrong • Tutorials and examples • StackExchange/StackOverflow
  6. 6. LIKE DON’T LIKE
  7. 7. CODEX != SUSTAINABLE
  8. 8. ROADMAP http://make.wordpress.org/docs/2013/06/19/docs-sprint-results-and-roadmap/
  9. 9. ROADMAP • Constrain the scope of docs to the core project • Reduce and refine • Separate developer from user documentation
  10. 10. 1. DEVELOPER HUB
  11. 11. 1. DEVELOPER HUB • Code Reference • Standards/Parser • Hook Docs • Code Reference Theme
  12. 12. CODE REFERENCE
  13. 13. EXAMPLE EXAMPLE
  14. 14. + 2. HANDBOOKS
  15. 15. 2. HANDBOOKS • Plugin, theme developers • Polyglots, users, etc. • Rewrite, focus the content • Reorganize
  16. 16. 3. SUPPORT HUB
  17. 17. 3. SUPPORT HUB • Getting Started, task-based guides • Knowledge base • Identifying cross-over content
  18. 18. 4. DISMANTLING THE CODEX
  19. 19. 4. DISMANTLING THE CODEX • Migrate remaining content to inline docs and explanations • Massive 301 redirect
  20. 20. WHAT’S NEXT
  21. 21. SHINY THINGS • Examples voting • Explanations • Hook aliases • Documenting default arguments
  22. 22. SHINY IDEAS • Adopt the JSDoc3 standard • Parsed JavaScript docs • Extended references • and …
  23. 23. Drew Jaynes | @DrewAPicture Slides: http://drewf.us/wcnyc

×