[wp-meta] [Making WordPress.org] #6001: Lack of Context for Docs (no learning path) under https://wordpress.org/support/

[Making WordPress.org]

#6001: Lack of Context for Docs (no learning path) under
https://wordpress.org/support/
--------------------------+---------------------
 Reporter:  juanmaguitar  |       Owner:  (none)
     Type:  enhancement   |      Status:  new
 Priority:  normal        |   Milestone:
Component:  HelpHub       |  Resolution:
 Keywords:                |
--------------------------+---------------------

Comment (by ironprogrammer):

 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 WordPress.org Documentation

 Unlike the [https://make.wordpress.org Make WordPress handbooks] and
 [https://developer.wordpress.org much of the Developer documentation], the
 [https://wordpress.org/support/ 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

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

 ==== [https://wordpress.org/support/ 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 `https://wordpress.org/support/`, create
 an intro page for each section, corresponding with each high-level
 category. For instance, the intro to "Installing WordPress" would be
 located at `https://wordpress.org/support/installing-wordpress/`.
 - For intro page content, it could be newly authored, or migrated from an
 existing support article. For example, the
 [https://wordpress.org/support/article/overview-of-wordpress/ 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,
 [https://wordpress.org/support/article/using-filezilla/ Using FileZilla]
 should fall under the parent page [https://wordpress.org/support/article
 /ftp-clients/ 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 ([https://developer.wordpress.org/coding-standards
 /wordpress-coding-standards/ like elsewhere on WordPress.org]).
 - 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:

 - Getting Started [https://wordpress.org/support/getting-started/]
   - New to WordPress [https://wordpress.org/support/getting-started/new-
 to-wordpress/]
   - ...
 - Installing WordPress [https://wordpress.org/support/installing-
 wordpress/]
   - Requirements [https://wordpress.org/support/installing-
 wordpress/requirements/]
   - ...
 - Basic Usage [https://wordpress.org/support/basic-usage/]
   - ...
 - ...

 ==== Existing Category Pages
 The category page has random ordering of articles under each category
 ([https://wordpress.org/support/category/getting-started/ 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.

 == Summary

 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!

-- 
Ticket URL: <https://meta.trac.wordpress.org/ticket/6001#comment:1>
Making WordPress.org <https://meta.trac.wordpress.org/>
Making WordPress.org