Welcome to the official home of the WordPress documentation team.
This team is responsible for all things documentation, including the Codex (moving to HelpHub), handbooks, developer.wordpress.org, admin help, inline docs, and other general wordsmithing across the WordPress project.
Want to get involved?
We need your help keeping content current with each WordPress release and adding new content and screenshots to:
With the release of WordPress 5.0 and the new Gutenberg block editor, there are many changes in WordPress for users and developers alike.
For developers in particular, the changes are dramatic. As such, we also have a lot of new documentation to create: and we need your help!
If you’re a developer and have spent time working with Gutenberg, this is your time to shine. We’re looking for contributions in a few specific areas.
Examples
Most of the requests we get are “how do I do X?”, so we are looking for code examples and “micro-tutorials” that can help developers solve these questions and integrate with Gutenberg.
Contributions here are ideally in the form of a single markdown file, with at least a few hundred words that describe the problem and walk users through the solution, with complete code examples. They should link out to the relevant API documentation (where it exists) or to other areas of the handbook that offer further context.
A few ideas for contributions include…
How to register a sidebar plugin
How you might use InnerBlocks
How you could port a custom metabox to a custom sidebar plugin
How to trigger a modal
How to write block attributes to post_meta
How to use the color HOCs and components in your blocks
How to filter specific areas of the editor (especially panels in the document settings sidebar)
How to filter the available blocks in the editor
How to use the data module to retrieve post data within a custom component
Package documentation
Gutenberg is built with a collection of npm packages. Some of these packages have great documentation in their READMEs, but others don’t. This is another great way to contribute: choose a package, and improve the README in a pull request on the GitHub repo.
Each README should include:
Installation instructions (most have this already!)
General/basic usage instructions
Function documentation, if applicable
Links to other documentation that might be relevant/helpful
Component documentation
The new editor also leverages Components to build the user interface. These are provided inside the @wordpress/components package. Each component should have its own README that contains:
Basic usage example
“Dos and Don’ts” of how to use the component correctly (from a UX perspective)
Although these are our highest priority items, they are by no means the only ways you can contribute. The “Documentation” label on GitHub offers many more ideas. Picking a ticket and writing the documentation to solve the issue is a great way to contribute.
We’re all committed to making Gutenberg documentation the best on the web. Thanks so much for your interest, and we hope you’ll also consider joining our weekly meeting in #docs in Slack at 18:00 UTC!
Thanks to everyone who joined us for the kick-off Gutenberg docs meeting!
Below is a summary of last week’s meeting.
Opened with introductions and hellos, and a description of @chrisvanpatten‘s goals for the group
Set future meetings for 1pm ET/17:00 UTC on Tuesdays, in #docs on Slack
Discussion of where documentation would “live”
Goal is to continue allowing docs to be prepared in GitHub
@drewapicture raised some questions about what the Gutenberg handbook represents, suggesting it not exist as a mono-doc when merged into core
@kenshino raised the idea of splitting into separate handbooks: auto-parsed documentation in DevHub, developer handbook in DevHub, and user handbook in HelpHub
(@chrisvanpatten also added a contributor handbook to be considered too, likely to live on GitHub for now)
Established next steps:
Lock down high level documentation outline
Open a PR to reorganise the documentation
Determine list of holes in documentation
Begin assigning writing tasks in GitHub issues/high level project/milestone
Established next meeting for Tuesday, 30 October at 1pm ET/17:00 UTC in #docs
</meeting>
I’ll post an agenda for our next meeting tomorrow a few hours before the meeting. Thank you everyone who joined us!
Project HelpHub is the user documentation base that will sit on WordPress.org/support. It's the companion to Developer's Hub which serves development documentation.
The general guiding philosophy for the design, content creation, and build of the project is – Help users help themselves.
We want users to be able to find answers on WordPress.org before posting on the forums. We want to make documentation more discoverable, through enabling search, visual improvements and concise targeted content.
We've been working on HelpHub for some time now and its possibly the final item that needs completion from the roadmap created by the Docs Team way back in 2013.
What’s the difference?
The biggest change is actually using WordPress to power content!
Shifting away from Codex was a deliberate decision
What we like about the Codex
What we hate about the Codex
Developer issues with the Codex
User issues with the Codex
Codex traffic breakdown
Scribbles the Docs Team did in 2013, suffice to say Codex wasn't enough
Too many pages that deal with the same issue (we have 4 getting started pages!)
Conflation of user and developer content
Content is hard to navigate
Content is way way way way way too verbose
Too much irrelevant content
Codex couldn't be realistically improved in it's functionality to deliver meaningful content
HelpHub aims to curate articles in a more concise way with standardised formatting and screenshots where possible.
Up-to-date screenshots
Consistent formatting, improved readability
Proper editing via WordPress back end & Gutenberg
Better categorisation & discovery
Gutenberg Editing
The possibility to add functionality as need arises
Adding read time to help keep articles concise
Current State
We want to release a minimum viable product, and we have classified it as such below:
MVP – Plenty better than Codex
Better content
Internal search
Improved readability through design and content re-writes
Better article discovery through better categorisation
REST API endpoints
Phase 2 & beyond – Iteration
Phase 2 & beyond will have the team working on the enhancements on top of the basic features. We'll keep iterating to make things more use-able, easier for people to collaborate and of course create better content.
Examples are
WordPress Search -> ElasticSearch
Simple input search -> Auto complete and Suggestions via JS
And more
We'll also work on new features based on understanding how well the basic ones work and what the general end public needs next. Such could be article voting, direct article contribution via Feedback or user guides for example.
Team
Many people came in to help, unfortunately, life happens. We will need some consistent help going forward.
It is also plainly obvious that having an overall project lead isn’t enough to help tackle the pre-launch needs, let alone the post launch ones.
They have already been doing these tasks but it would be great to properly introduce them
Our focus right now is to complete the development work for MVP and also work with the Meta and Support Team to properly setup HelpHub on WordPress.org
We aim to release HelpHub latest by 31st May 2018. We are working however to release it earlier than that.
Progress of Phase 1 (MVP)
Articles are appropriately categorised
Many popular articles were re-written
General WordPress.org styling are being merged in
We're now focusing on the tasks needed to ensure proper integration to be the Hub Page of WordPress.org/support
What do we need?
Developers. Consistent developers who are familiar with WordPress & PHP coding standards and good practices.
Content Migrators and Editors who are familiar with editing in WordPress.
If you would like to join us, you can do so in the following ways
Comment here
Join us at HelpHub meetings Tuesdays at 15:00 UTC in #docs
We have the the staging version of the site up. (It still requires a fair bit of styling fix but the fundamental code to run it is in). It's not the prettiest right now but we're working on it. And we could certainly use your help!.
The Seattle WP Meetup’s next monthly WordPress Docs Sprint is coming up on Saturday, November 1st.
We need all experience levels – this isn’t just for coders. We need writers, screenshot-takers, editors, readers, and of course, developers. If you show up, we’ll find a way you can help.
Questions
What if you’re not in the Seattle/Tacoma area?
We’ll use Slack for team communication while we’re at the meetup, so if you’re joining from another state, country, or planet, you can participate as long as you’ve got a good internet connection.
If you don’t already have a Slack account, go to https://make.wordpress.org/chat/ and signup for an account. Once you log in, join us in the #docs channel.
For most people, the toughest roadblock to contributing is just getting started, so hopefully this will help.
Where to Go
The jumping off point for all docs-related efforts is: make.wordpress.org/docs/ – In the sidebar, you’ll see links to the Handbooks along with the Spreadsheets we use to track their progress.
The Theme Developer Handbook is at: http://bit.ly/WPThemeHB
. . . and the spreadsheet that we use to track Theme Developer Handbook progress is at: http://bit.ly/WPThemeHB_Content
The Plugin Developer Handbook is at: http://bit.ly/WPPluginHB
. . . and the spreadsheet that we use to track Plugin Developer Handbook progress is at: http://bit.ly/WPPluginHB_Content
The IRC channel we use is at #wordpress-sfd on Freenode.
This is a great place to ask questions, post links to docs for review, and cheer each-other on.
Find a topic in the Theme or Plugin developer spreadsheet that interests you
Check the Needs column of the spreadsheet to see if there are specific things that are needed in this document
Add your name to the Responsible column in the spreadsheet
Write or edit in HTML or Markdown and give it to Mario Peshev or email it over to me at eric [at] ivycat.com and we’ll post for you.
What if I’m not a Writer?
If you’re not comfortable writing or editing, you can also help by:
Creating code snippets for examples
Taking relevant screenshots
Reading existing documentation and making comments regarding improvements
If you’re completely overwhelmed and not sure where to start, you might start by reading through the Handbook and, when you’ve got questions, find missing content, or see improvements, please feel free to work on the document, or make comments in that document’s comment section.
I’m here to help in any way I can, so feel free to ping me (@sewmyheadon) or Mario (@no_fear_inc), or post to the #wordpress-sfd IRC channel if you have any questions.
The Seattle WordPress Meetup is holding monthly WordPress Docs Improvement Meetups at a local coffee shop. So far, around 6 – 8 people attend each meetup, and the group has worked on docs in the Codex, Handbooks, and Function Reference.
The Docs Team would love to see other WordPress Meetups and local WordPress groups hold their own Documentation Meetups. Of course, Docs can use all the help it can get.
Things to keep in mind when organizing a Docs Meetup
Your location needs good internet access and power outlets. Duh, right? Great coffee also helps.
Figure out what to work on in advance. The hardest thing about contributing to these meetups is simply figuring out what to work on. So, as an organizer, prepare in advance by finding a handful of specific things that the group can work on. Keep it small and manageable. You can touch base with one of the Handbook editors, Docs Team Members, @hanni or @siobhan or @sewmyheadon to help make your list. There’s always plenty to do, but some things need quicker attention.
Publicize it. Ask people to contribute and encourage participation of all user levels. You don’t have to be a developer or designer to contribute. There are plenty of things you can do to help including:
Screenshots – we need folks to take, and edit, screenshots to augment written documentation
Examples & Code Snippets – need formatted code snippets and examples
Editing / Proofreading / QA
Transcribing video to text
Developer support – non-devs need coders to help clarify functions, hooks & filters.
Post pre-meetup instructions. Before your meetup date, make sure to post some pre-meetup instructions so new contributors can be prepared when they come. Here’s an example of a Docs Improvement post from the Seattle WP Meetup site. At minimum, you’ll want to make sure people have reviewed the
Prepare to be a helper. Organizers should expect to spend about 30 to 50% of their time at the Meetups just helping others get situated, reviewing other’s docs, answering questions, etc.
Be okay with slow progress. Writing docs isn’t always a quick task, in fact, it’s usually the opposite. It’s a win if you can complete one or two documents in one 4 – 6 hour Meetup.
Join the #wordpress-sfd IRC chat room. During Docs Meetups, we encourage folks to login to IRC so they can ask questions, post progress, request docs reviews, and generally help out.
Be encouraging. Face it, writing docs can be relatively thankless and sometimes tedious work, so make sure to be positive, thank people for their participation, and be encouraging. The sooner someone feels like they’re contributing and their work is appreciated, the more likely they are to continue helping.
Have fun.
Join Us
If you’d like to participate in any of the already-scheduled Docs Improvement Meetups in-person in Seattle or virtually via IRC, here’s when we’re meeting:
@westi shared this article on writing docs with me: http://stevelosh.com/blog/2013/09/teach-dont-tell/ It’s a great read and very relevant for what we’re doing on dev.wp.org. I recommend you all read it 🙂
