Documentation Issue Tracker on GitHub: Submit any Documentation Team-related issues on GitHubGitHubGitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/
Join our discussions of documentation issues here on the blog and on Slack.
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
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.
pluginPluginA 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
introduction to WordPress development (how WP works, the loopLoopThe 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)
All of this content should be optimized for search.
What tools do we need?
method for surfacing revisionsRevisionsThe 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 betaBetaA 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 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 coreCoreCore 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 APIAPIAn 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.
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 ContributorsCore 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.
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 UIUIUI 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., UXUXUX 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.
Project: Code Reference
Simultaneous work on tools for the next cycle
attribution and credit
handbook virtual sprints
Project: Developer resources landing page and site – follows directly from the code reference
Project: Support Hub
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.