estelaris 10:58 pm on February 1, 2021  

Requirements for a new design for the article pages in user documentation

This is post one on a four-part series. The focus on these series is the redesign of documentation that will include a new template, new categorization, new navigation and some renaming of articles. On this post, we will focus on requirements.

Some of these requirements are very straight forward, others still need a bit of discussion. The links to the PRs are included. 

List of requirements:

  1. Article voting (#7) vs feedback: contributions from the public (#240)
  2. Search area (#9)
  3. SidebarSidebar A sidebar in WordPress is referred to a widget-ready area used by WordPress themes to display information that is not a part of the main content. It is not always a vertical column on the side. It can be a horizontal rectangle below or above the content area, footer, header, or any where in the theme. navigation styling (#111)
  4. TOC styling (see #111)
  5. Language (#201) vs localization (#283)
  6. CategoryCategory The 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging. terms archive (#231)
  7. Mobile view (#235)
  8. Mobile sidebar (#236)
  9. WP version page (#245)
  10. Add changelog (example)
  11. Index dev notes by release (example)
  12. 404 with link to forum (#47)
  13. Icon for external links (example)
  14. Add breadcrumbs
  15. Change hovering anchor# icon

1. Article voting (#7) vs feedback: contributions from the public (#240)

The difference between “article voting” and “feedback: contributions from the public” is the type of information we gather from the user. 

Is knowing if an article is useful to a user, better than having the user’s feedback? Is there a way to merge both? Or do we want to keep them both and separate? Or would only one fulfill the documentation goals?

At the moment, there is a feedback form being tried out. The questions are: Was this article helpful? How could it be improved? The reply box is for a long comment and none of these replies/feedback is posted online.

Question is, being that the features require different information and some articles are already too long, do we need both features?

Article voting recommendation

No triggers a feedback box:

And the article will show the number of yes replies

Feedback: contributions from the public (the form that is being tested in WP.org at the moment this post was written)

2. Search area (#9)

Maintain the search area for documentation and forums. Make it prominent for mobile.

3. Sidebar navigation styling (#111)

Follow the new style for pages in WP.org. Use only the main category items on the menu with links to each subcategory TOC pages

4. TOC styling (see #111)

5. Language (#201) vs localization (#283)

Are there Rosetta sites that will not be using the HelpHub pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party to translate documentation? Is it still necessary to add the language feature? 

6. Category terms archive (#231)

This PR will be resolved with the new classification for the articles that was done via GSoD.

7. Mobile view (#235)

Currently the view on mobile for documentation uses a very large band and it gives the impression that there is nothing else. So increase information above the fold.

8. Mobile sidebar (#236)

The sidebar on the mobile version will be affected with the new navigation. At the moment, it looks like this:

9. WP version page (#245)

There will be a review but will use the same template as the documentation articles.

10. Add changelog (example)

A changelog is essential to keep users informed on what has been changed and when. It is being tested at the time this post was written.

11. Indexed dev notes by release (example)

Although the dev notes are written for developers, the docs team is interested in keeping an index page of all the dev notes written for a release. The index page will be linked from the release version page. 

12. 404-not-found with link to the forum (#47)

The new design will include a 404 page with a link to the support forums.

13. Icon for external links (example)

In the article template, include an icon to highlight a recommended site or external link. 

14. Add breadcrumbs for navigation

Breadcrumbs will be added to ease navigation

15. Change hovering anchor icon

Nowadays the hashtag # symbol has other connotations as it is common in social media. The link icon is commonly used as a hovering anchor  

This list is by far what the docs team has gathered. The post will be open for discussion and recommendations until 12 February 2021. 

The next posts on this series will be:

Part 2: Documentation: a different classification, navigation and SEO

Part 3: Draft templates for article documentation 

Part 4: Proposal for a new design for documentation 

Props @milana_cap for proofreading and final review.