Background

While working on a new design for HelpHub or documentation in WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/, we discovered that the implementation of a menu or a table of contents was difficult because the articles were included in several categories.

Documentation is maintained manually by contributors and it is being moved from the old Codex. The structure is 17 years old and as WordPress develops and grows, the categories that worked 5 or 10 years ago are not necessarily the same that work now.

In order to continue with the design of documentation, we need to define a documentation structure that is clear and fulfills the user’s needs.

Problems with the actual categorization

The issues below affect the way users consult the articles in the documentation section.

• There is a lack of definition of user personas. 
• Search is not user-friendly because navigation is not clear, making article discoverability challenging. 
• Inside a categoryCategory The 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging. with several pages, articles jump order, making navigation confusing.
• Some titles are not descriptive enough or use only one word.

What are we looking for

It is important to define first what the goal is for the documentation structure in order to define the categories. Envisioning what our ideal documentation section should look like:

• It should be easy to navigate: a user should understand where they are.
• Categories should be broken into subcategories to ease mobile navigation.
• Categories should be descriptive enough to quickly answer the question: “where does this article go?”
• It should be reliable: if an article is not found where it should be, it means that the article simply doesn’t exist
• Titles should be descriptive enough for any type of user to understand what the article is about.
• Maintenance or updating of the articles should be easy with a clear documentation structure
• The structure should allow the incorporation of new categories or subcategories as the software develops.

The docs team worked on creating some stories that can help us verify if the proposed solution will work. You can find the complete list of stories here:

• If I am new to WordPress, how do I know if it is the right CMS for my project?
• If I am a blogger who receives many comments, is my data secure in WordPress?
• If I am not a developer, can I still create a website and add my own branding?
• If I am a business owner, can I sell products in WordPress?
• If I am a website designer, where can I find information about new releases and upcoming features?

What documentation looks like now

So far, there are 171 articles being moved from Codex into HelpHub. Separately there are new articles being written about the blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. editor, so far 40 articles have been added and there are plans for more.

In the image below, we can see a snapshot of how articles are included in several categories. At the moment, the articles were arranged in alphabetical order because the articles jump order while scrolling through the pages:

Example scenario

Let’s review an example from the image above where the articles jump order inside a category with multiple pages.

In the video below, we are looking at the category Getting Started. A session was recorded following the Next Page link at the bottom of the page and then returned to the first page following the Previous Page link. The first page at the beginning has different articles than the first page that we returned to.

What it is like on a computer

The first page begins with the following list of articles:

• Appearance Menus Screen
• Backing Up Your WordPress Files
• Pages Add New Screen
• New to WordPress – Where to Start
• Administering Your Blog
• Resetting Your Password
• Creating a Search Page
• Managing Plugins

We navigated to the last page via the Next Page link at the bottom of the page and then returned to the first page, using the Previous Page link.

When arriving to the first page, the list of articles is different from what we have above:

• Comments in WordPress
• phpMyAdmin
• Creating a Static Front PageStatic Front Page A WordPress website can have a dynamic blog-like front page, or a “static front page” which is used to show customized content. Typically this is the first page you see when you visit a site url, like wordpress.org for example.
• Users Your Profile Screen
• Update Services
• Settings Writing Screen
• Administration Screens
• Giving WordPress Its Own Directory
• Settings Reading Screen
• Dashboard Screen

What it is like on mobile

On mobile, the situation is the same. 

Looking into the future

Target audience

As mentioned before, the end-user of documentation is not well defined but the existing documentation can shed some  light into identifying who the users are.

Who is the content intended for? 

From the stories written, we can identify some groups, but we have not explored the many user personas that access the documentation. Here are some examples:

• New users looking for a CMS to build a website.
• Bloggers/website designers that want to customize a site.
• Content creators looking for content to write tutorials/posts.
• WordPress consultants that provide services to their clients.
• Others?

Type of content

In order to define a navigation structure that suits the project and allows for growth, we need to explore information pillars. Pillars shouldn’t be more than 4 or 5, as these can be split into categories and subcategories to form a logical navigation structure. These are suggestions for information pillars:

• WP basics – overview, features, history, glossary, semantics, contributing.
• Technical documentation: installation guides, requirements, best practices, technical how-to, security, troubleshooting.
• Support documentation – dashboard structure, user permissions, screens, media screens.
• Project related documentation – customization, themes & plugins, design how-to’s (blocks)

Relation to time and development

There are articles that have been superseded by new development and are either no longer relevant to the software itself or must be updated. We need to include 4 buckets where we should add articles:

• No longer relevant or valid
• Need update
• Convert from Codex as is
• Create new documentation

Next Steps? 

The docs team will continue working on defining the user personas, as well as the information pillars.

We plan on having a proposal on documentation structure that includes clear navigation and new classification, by the end of the summer.

If you would like to contribute to the project, leave your comments. Comments will be discussed during the #docs team meetings on Mondays at 15:00 UTC