[HelpHub] Proposal: Find ways to simplify the end user documentation and reduce the maintenance burden

[ndiego]

While helping log issues for the WordPress 6.7 release, I spent some time looking through the existing documentation as well as the outstanding issues from previous releases. For example, here's the list for 6.6.

There’s undoubtedly a lot of work to do, more than the current number of contributors can handle. While bringing in more contributors, including myself, would help with end-user documentation, I wonder if there are changes we can make to simplify the documentation and make it easier to maintain.

Here are two examples I stumbled upon today.

Remove the "Blocks that include X" sections

There are a number of docs that include big lists of core blocks to indicate the block supports the feature that the article covers. Here's an example from the Layout Settings overview doc. These lists are curated manually and, in many cases, are out of date.

However, each block has its own doc that also needs to be updated when it gains layout support (in this example).

Rather than updating content in both places, the Layout Settings overview should just be a generic article discussing how the layout options work (remove the list). Each block article should then link to the Layout Settings overview doc if layout is supported.

Remove duplicate content throughout

Here's a simple example using the Block toolbar section of the Group block doc. This section includes standard information that is common across many blocks. It even includes links to two designated articles about Move Handles and More Options, yet it includes two screenshots and lots of content that needs to be managed. It also doesn't include info about transformations like in this article for the Separator block.

Instead, we could just link to the relevant articles (and add one for alignment and transforms). Obviously, the copy would need to be adjusted in the screenshot below, but this approach will greatly simplify the maintenance of each block article. The Block Toolbar section would only detail functionality that is unique to the block itself and link to standardized documentation for more ubiquitous features.

Current doc	Simplified version

Next steps

There are certainly more examples like these. With limited resources available for improving end-user documentation, the best way forward seems to be simplifying the docs and reducing the maintenance burden. What are your thoughts?

[github-actions[bot]]

Heads up @WordPress/docs-issues-coordinators, we have a new issue open. Time to use 'em labels.

[estelaris]

This looks like a reasonable solution. There should be more examples like this, but I see that it cn also help us close a number of issues that suggest/request this type of update.

[carolinan]

Users asking which blocks support which feature is very common. Instead of removing it, can this information not be provided a by a plugin, automated? Because this can be parsed from the block library.

[bph]

It might help with the question about block supports to add this Roster somewhere and somehow to the documentation. https://make.wordpress.org/core/2024/10/17/roster-of-design-tools-per-block-wordpress-6-6-edition-2/

[carolinan]

Yes but that is also my point. You should not need to do that table manually 😃

[ndiego]

Users asking which blocks support which feature is very common. Instead of removing it, can this information not be provided a by a plugin, automated? Because this can be parsed from the block library. Yes but that is also my point. You should not need to do that table manually 😃

Yeah, definitely should not be manual.

Each block article already needs updating and should "ideally" inform the user what styles/settings are available for each. I recommend we:

1. Remove the manual lists
2. Audit each block article and ensure each is up to date (I can volunteer for this over the next few months)
3. Explore a solution that will display all blocks that support a specific block support