Redesigning the end-user documentation in the WordPress project – case study

For the past 2 years I have been busy reading and reviewing the end-user documentation in The goal was to create a new design for the articles as they look outdated. The hidden problem was the problematic search, which is far more important than the way a page looks. This project is written into two parts.

The discovery phase

While reviewing the documentation, I found discrepancies in the navigation. Discovered that several articles were included in more than one category, the article listing changed when going back in the browser and there was no clear navigation.

The revision included the 15 requirements that the documentation team had gathered during the migration of the documentation from the Codex (the previous documentation repository for the WordPress Project.)

The most urgent issues to solve were the navigation to improve search and the user experience and, identifying the users.


I didn’t follow any specific methodology. After researching documentation sites for several software companies, open-source and privately-owned, I understood the path to follow.

The path guided to find the four pillars to create the sitemap. When thinking of how to structure end-user documentation it is difficult to think about new, intermediate or advanced users because one cannot really identify who is whom or what level is each user. Instead, it is best to follow a “step-by-step” build; what do I need to know before building a site, what are the requirements, any technical hiccups (maintenance), etc.

  1. What is WordPress? What is its story? Is WordPress the best CMS for the user’s project?
  2. What does the user need to create and maintain a WordPress blog or site? First steps, requirements, maintenance, troubleshooting
  3. WordPress dashboard – daunting for new users, get to know your new software, how to add content, how to manage media.
  4. Customization – themes, blocks, FSE, plugins, colors, etc.

Identifying the end-users

Creating personas for a software that is used by millions of people is absolutely useless. As soon as one persona is created, you leave out 99% of the users. Instead, I identified users by roles.

The non-developer users that search WordPress end-user documentation falls into any of these roles:

  • Bloggers – new or not, anyone who writes a blog and wants to customize it without the help of a developer.
  • New users looking for a CMS to build a website.
  • Content creators that are looking for content to create tutorials or references for their own products.
  • WordPress consultants that provide service to clients.
  • Support teams from companies that look for content to support their own products/services or, that provides tech support for their clients.
  • Translation teams/contributors that are translating documentation into their own languages.

The result: a new site map for Helphub

There were 170 articles written when we started the reclassification. The new WordPress features including the Block Editor, Full Site Editing and new blocks, increased the number of articles to about 250 and there are plans to write more. The reclassification needs to take into account the growing needs of WordPress.

The site map now includes 4 main categories with subcategories under each to allow growth. Below is an image of the recommended sitemap. The developers column is under review.

Image and link to the recommended new site map for end-user documentation in the WordPress project.
The recommended new site map for HelpHub in