Welcome to the official home of the WordPress Documentation Team.
This team is responsible for coordinating all documentation initiatives around WordPress, including the handbooks and other general wordsmithing across the WordPress project.
Want to get involved?
Start here to find out more about what we do and how to contribute:
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/
Weekly meetings
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
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.
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
theme 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)
knowledgebase
glossary
All of this content should be optimized for search.
What tools do we need?
multilingual support
editing/approval flow
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.
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 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.
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 JavascriptJavaScriptJavaScript 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 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.
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.
