Docs Sprint Results and Roadmap

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

Users:

  • support hub (like Mozilla & WP.com)
  • “get started with your blog”
  • “get started with your website”
  • task-based documentation
  • glossary?

Developers

  • developer resources hub (like WP.com and Stripe)
  • code reference
  • pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party handbook
  • theme handbook
  • introduction to WordPress development (how WP works, the loopLoop The Loop is PHP code used by WordPress to display posts. Using The Loop, WordPress processes each post to be displayed on the current page, and formats it according to how it matches specified criteria within The Loop tags. Any HTML or PHP code in the Loop will be processed on each post. https://codex.wordpress.org/The_Loop., etc)
  • knowledgebase
  • glossary

All of this content should be optimized for search.

What tools do we need?

  • multilingual support
  • editing/approval flow
  • method for surfacing revisionsRevisions The WordPress revisions system stores a record of each saved draft or published update. The revision system allows you to see what changes were made in each revision by dragging a slider (or using the Next/Previous buttons). The display indicates what has changed in each revision.
  • attribution and credits
  • code reference betaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process.
  • 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 releaseRelease A release is the distribution of the final version of an application. A software release may be either public or private and generally constitutes the initial or new generation of a new or upgraded application. A release is preceded by the distribution of alpha and then beta versions of the software. 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 coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. 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 APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. docs, but not for user docs. Our user docs should be written only for the latest version of WordPress.

Challenges

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 contributorsCore Contributors Core contributors are those who have worked on a release of WordPress, by creating the functions or finding and patching bugs. These contributions are done through Trac. https://core.trac.wordpress.org.,” 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.

Learning Blogs

Currently, the Codex is used as a dumping ground for every type of content relating to WordPress that doesn’t fit on the blog. For example, we created a page on troubleshooting JavascriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. for the last WP release. In the absence of MediaWiki, we’ll need a place for these types of things. The support and developer resources could each have blogs that contain time-related resources, such as dev docs related to recent releases, or user docs relating to recent releases/events (e.g. how to migrate from Posterous, how to use the new media uploader, etc).

Help Tabs

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 UIUI UI is an acronym for User Interface - the layout of the page the user interacts with. Think ‘how are they doing that’ and less about what they are doing., UXUX UX is an acronym for User Experience - the way the user uses the UI. Think ‘what they are doing’ and less about how they do it., 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.

Roadmap

July–Dec 2013

  • Project: Code Reference
  • Simultaneous work on tools for the next cycle
  • multilingual plugin
  • editing flow
  • revision surfacing
  • attribution and credit
  • handbook virtual sprints

Jan–Apr 2014

  • Project: Developer resources landing page and site – follows directly from the code reference

May–Dec 2014

  • 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

Jan–Mar 2015

  • 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

End Goals

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