Update on the revision of documentation

This article is part of the Help Hub redesign series. Previous articles on this project at listed at the bottom.

As previously established, the Help Hub articles have problematic navigation as they are now. There are numerous reasons why that has happened but the new plan focuses on better use of categories.

As of now, there are 9 main categories and some articles have 2 or more categories making the navigation confusing. Another issue is that the landing page does not contain a table of contents per se, instead shows links to some articles.

The plan is to create 4 pillars and add categories to each pillar. Because this work is not done, there will be another post with more details. Let’s talk about the articles.

The proposal for a new navigation includes reading, reviewing, and classifying each one of the 170+ articles on Help Hub plus the articles for 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.

What are we reviewing?

  • Content: what is the article about? wherein the website creation does it fall into?
  • Codex links: are links still directing to a Codex page? does that Codex page still exists or has been migrated (without updating the link)?
  • Information: is the feature/process/tool described/recommended still valid or are they outdated?
  • External links: are links up-to-date or are they too old? is the link directing to a 404? flag all external links for docs team review.
  • Structure: are there too many links in the same paragraph? is the article following the new style guide (wording, headlines, punctuation, etc.)
  • Code snippets: are they well structured? is the code complete? are they needed?
  • Images: is it a good example? is it the latest version?

We feel that the revision is not exhaustive, but we will be as detailed as time and resources allow it. The work is being tracked on a spreadsheet because it needs to be reviewed by different contributors:

The process

The revision of articles began as a project under the 2020 Google Season of Docs. The assessment done by the GSoD technical writer included title changes and suggestions of merging/deleting pages with repeated or similar content. @dmivelli also came up with a first navigation proposal.

As a designer, I am reading each article to understand the documentation structure and can propose logical navigation, and at the same time, making recommendations on outdated content, structure, flag links, and image updates.

@atachibana from the documentation team is commenting on my recommendations, finding new links to replace flagged links and revisiting outdated content.

We still need the review of a developer to check on the code snippets and other technical information we are not familiar with.

Before making any updates to the articles, the documentation team will have a chance to have a final assessment.

We are working as fast as we can, but we need help with reviewing. If you are interested in helping to review articles and giving your recommendations, please reach out to @estelaris on the #docs SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. channel.

Previous articles

Props to @zzap and @atachibana for post edits.