Core Docs: Sentencing WordPress to 11-years-to-life
25
CORE DOCS: SENTENCING WORDPRESS TO 11-YEARS-TO-LIFE
-
Upload
drewapicture -
Category
Education
-
view
359 -
download
0
description
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.
Transcript of Core Docs: Sentencing WordPress to 11-years-to-life
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 …
