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?