Opened 2 years ago

Last modified 2 years ago

#6001 new enhancement

Lack of Context for Docs (no learning path) under

Reported by: juanmaguitar's profile juanmaguitar Owned by:
Milestone: Priority: normal
Component: HelpHub ( Keywords:


Issue Description
When we visit a doc like [Blocks]( there are no resources to follow a "learning path"

![diagram docs blocks](

So when a user get to this documents there is no answer to the questions: Where am i? Where should I go next? What should I have read before?

URL of the Page with the Issue
This one is an example but any page under have the same problem

Why is this a problem?
Because I think is super hard for any user to learn about any of the topics provided in the docs if they cannot establish an order and hierarchy of the docs they are reading

Suggested Fix

  • Establish a clear hierarchy of docs and categories
  • Highlight in the sidebar the category the current document belongs to
  • Suggest knowledge recommended to understand the current document
  • Suggest docs to read after reading the current document
  • Highlight in the top bar where we are

Change History (1)

#1 @ironprogrammer
2 years ago

Thank you, @juanmaguitar, for raising this topic! While providing support in the forums, I also found the documentation difficult to navigate. I can't imagine how challenging this must be for newcomers to WordPress.

I would like to add some additional observations and suggestions to explore. There is some overlap here with the ticket description, but I would like to include it for context.

Support Is Inconsistent with Other Documentation

Unlike the Make WordPress handbooks and much of the Developer documentation, the Support docs use categories, rather than pages. This presents challenges like:

  • Establishing a hierarchical view requires customization/curation.
  • It is difficult to quantify available support articles.
  • It is difficult for users to navigate to related content.
  • Users cannot easily gauge which articles they’ve viewed, or which should be read next.

Why Does This Matter?

  • The approachability of support documentation is critical for the WordPress community when seeking self-help. With no clear navigational structure, users have little idea what help is available.
  • If users are unable to easily navigate support docs, they are probably more likely to post new topics to the forums. This poses a significant slowdown toward resolution, especially if the answer already exists in the docs.
  • Over time, these issues increase the likelihood of redundant or outdated content.
  • Forum topics related to common issues that are covered in the support docs consume valuable contributor time, where they could be helping resolve less common problems.

Suggestions to Improve Discoverability of Support Documentation

To summarize, make the Support documentation follow a hierachical structure like that of the Make and Developer sections of This includes left-side navigation that shows the position of the current document in the overall tree.

Support Landing Page

This page features a curated list of key starting points for support seekers. It should continue to function as such, so no change recommended.

Support Articles

Once a user has searched or navigated to a particular support article, the power of the left sidebar becomes evident. Articles and the "single page" view could be updated like this:

  • Treat existing "Support Categories" as "Support Sections".
  • Nested under the canonical URL, create an intro page for each section, corresponding with each high-level category. For instance, the intro to "Installing WordPress" would be located at
  • For intro page content, it could be newly authored, or migrated from an existing support article. For example, the Overview of WordPress content could become the copy used in the "Getting Started" section intro.
  • Organize existing articles in a rational order under each of their intro sections (formerly categories). The order could be based on workflow or technical difficulty. (This may require migrating posts to pages.)
  • Some articles, when viewed in the context of this hierarchy, might make more sense to be moved under a different section.
  • Nest similar articles under parent pages, as necessary. For example, Using FileZilla should fall under the parent page FTP Clients.
  • Replace the left sidebar "Categories" navigation with a hierarchical view. The nav should show the position of the existing article within the document hierarchy (like elsewhere on
  • Having a "Search Documentation" box above the left navigation would also be useful, and would be consistent with other parts of the site.
  • Above the footer of each page, display "Previous / Next" links that correspond with the hierarchy of the document (like on Make Handbook pages).
  • Redirect old article locations to their new URLs.

Final URLs for the migrated hierarchical content might appear similar to this:

Existing Category Pages

The category page has random ordering of articles under each category (e.g. "Getting Started"), and lacks page or article counts in its pagination.

This "random support article" view is of questionable utility to users looking for specific information. Rather than keep these pages around, each "category archive" page should be redirected to their new section intro pages.


These changes would make Support more easily navigable, similar to the Make and Developer documentation. With more accessible documentation, users should be able to find answers more quickly than asking on the forums, or seeking help on 3rd party sites that may have outdated content.

Thank you, @annezazu, for pointing me to this existing ticket!

Note: See TracTickets for help on using tickets.