We’ve spent three days in Cincinnati and it’s been hugely productive to get together and talk about the issues. We’ve also got some work done on the Theme Developer Handbook and the Codex.
Thanks to Kim Parsell, Drew Jaynes, Maria Scarpello, Eric Amundson, Ryan Ray, Ryan Markel, Hanni Ross, Jerry Bates, and Michael Krapf for attending. It’s been fantastic to get docs folks together to talk, work, and hang out in person. Also thanks to Automattic, WooThemes, and 10up for supporting the event.
What follows are the results of the discussions that we had, along with a Documentation roadmap for the next two years.
From the Discussions
Issues that we face
We spent a lot of time discussing the issues that we currently face. This was backed up by the responses to the Codex survey, which we analysed at length. Some of the issues we have are:
- Function Reference lacking examples, or examples are out of date
- duplicate content
- out-of-date content
- Too many pages that deal with the same issue (we have 4 getting started pages!)
- conflation of user and developer content
- the lack of responses from WordPress users demonstrates that we aren’t meeting their needs and they’re going elsewhere for their content.
- content is hard to navigate
- content is way way way way way too verbose
- too much irrelevant content
Documentation we need
- support hub (like Mozilla & WP.com)
- “get started with your blog”
- “get started with your website”
- task-based documentation
- developer resources hub (like WP.com and Stripe)
- code reference
- plugin handbook
- theme handbook
- introduction to WordPress development (how WP works, the loop, etc)
All of this content should be optimized for search.
What tools do we need?
- multilingual support
- editing/approval flow
- method for surfacing revisions
- attribution and credits
- code reference beta
- issue tracking system
Things we can do for quick impact
noindex forum posts over a certain age
- reduce the content on the Codex pages that get a lot of traffic
Project Management Model
Upon reflection, it makes sense for the documentation team to work on one focused project at a time. We discussed adopting a model similar to the development release cycle. We will work on a project together for a period of time. Each project will have a lead (or two leads, as necessary), which will become the primary focus of the whole team for its duration.
These cycles will be independent of the scheduling for core development cycles.
What versions of WordPress do we support?
The Codex has a lot of content that refers to different WordPress versions. For example, the Post Formats page uses phrasing like “Since WordPress 3.1….”. This makes sense for API docs, but not for user docs. Our user docs should be written only for the latest version of WordPress.
The biggest challenge that we face is dealing with 10 years’ worth of content – this also means we are dealing with 10 years’ worth of incoming links. We can’t just delete pages; they have to be redirected. With every page (particularly those with large amounts of traffic), we’ll have to decide where to redirect them. This will be particularly difficult on pages that contain developer and user information – where do we direct the page to? The user docs or the developer docs?
Analytics & Optimization
To make decisions about where to direct pages and what documentation will have the highest impact, it will be useful to do some analytics on the Codex. Redirecting the pages will be easier if we know the types of articles that are linking to the Codex.
We should also do some research into the information people are finding via Google. For example, we can do searches for issues like “WordPress white screen of death” to see what results people are getting. Where are they getting their help? What are the top results on Google?
Once we have created different documentation types we should carry out user tests to make sure they are effective.
Credits and Attribution
To engage and retain new contributors we need a proper attribution and recognition model. Currently there are no “recent rockstars,” “core contributors,” etc. for support or docs. This was a major issue for people who responded to the Codex survey. Acknowledging contributions will raise awareness that this is a way to get involved with WordPress and encourage new people to get involved.
We discussed the inline Help Tabs in the WordPress Admin. While we agreed that they’re currently not much help, any improvements to these would need to happen in connection with the core development team to make sure that the UI, UX, and content are best suiting users’ needs. If the core team decides that they want to make improvements to the help tabs, we’d love to work on that with them.
- Project: Code Reference
- Simultaneous work on tools for the next cycle
- multilingual plugin
- editing flow
- revision surfacing
- attribution and credit
- handbook virtual sprints
- Project: Developer resources landing page and site – follows directly from the code reference
- Project: Support Hub
- landing page
- Getting Started guides for websites and blogs
- Task-based and search optimized guides
- investigation into whether we need a knowledgebase for reference
- Dismantling the Codex (i.e., MediaWiki)
- Moving and removing any remaining documentation
- Setting up final redirects
- Any further hub pages that need to be written
The ongoing goal of the project is to reduce the amount of documentation for WordPress by reducing its scope to constrain it to the core project. This will be done by both eliminating unnecessary chunks of documentation and making successor documentation more concise. Separating user documentation from developer documentation will reduce confusion and aid in identifying documentation that can be pruned.
At the end of the two years outlined here, the goal is to retire the MediaWiki version of the Codex and have a fully-developed, effective, and usable WordPress-based documentation source.
Gallery of team scribbles
What we like about the Codex
What we hate about the Codex
Codex traffic breakdown
User issues with the Codex
Developer issues with the Codex
What docs do users need?
What docs do developers need?
Small changes/big impact
Rough wireframe for user hub
Docs roadmap and goals
Priorities by audience
Tools needed for the docs sites
Theme dev handbook topics
Intro to WP for developers