Documentation migration makes significant sections of the Drupal 8 handbook unnavigable or redirect to Drupal 7 docs

Weeks or months ago, the handbook documentation was navigated to a new content type to try to improve the documentation user experience. One component of this migration was to attempt to create separate handbooks for D7 and D8.

In practice, this has worked out really poorly.

  • Most aliases linked from extensive D8 content (including Drupal core itself and undoubtedly thousands of D8 resources across the web) now redirect to Drupal 7 pages. I just reviewed #2854586: Stark’s helptext link redirects to D7 theme guide today and realized that probably a majority of the d.o links we reference in core have issues like this.
  • Significant sections of the handbook for D8 are just missing.
  • Many pages that were authored primarily about D8 are now at Drupal 7 URLs.
  • Drupal 8 sections are now extremely poorly organized, missing huge chunks of content, confusing, uninformative, and pretty much unnavigable. The example alexpott spent a lot of time unsuccessfully trying to improve earlier this week: https://www.drupal.org/docs/8/testing I have no idea how that was the end result of the previous D8 content, but it just does not have the information I need, information that I used to be able to find. I don’t understand the two child pages or the related content. I can’t find the actually relevant docs for D8.
  • alexpott reported he did not have sufficient permission to add a page to a guide – for example https://www.drupal.org/docs/8/testing/types-of-tests-in-drupal-8
  • alexpott also reported that “guide” pages’ limit of 1000 characters (apparently) was insufficient to provide sufficient context for the child content, and that some of them could not even be saved because the content in them was already too long before the update and failed validation. For example: https://www.drupal.org/docs/8/phpunit

I’ve marked this issue as a critical bug because for D8 docs at least it continues to prevent normal use of the handbook and obscure rather than clarify. I don’t know what to do about this problem. When the initial migration happened I assumed it would gradually be worked out as followups to the migration were added, but it has not been.


Source: https://www.drupal.org/project/issues/rss/documentation