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.

Comments

xjm created an issue. See original summary.

xjm’s picture

Filed #2855175: [META] Many documentation / handbook URLs redirect to D7 content to try to fix core, but the problem is much bigger than that.

xjm’s picture

Issue summary: View changes
xjm’s picture

Issue summary: View changes
alexpott’s picture

Issue summary: View changes
alexpott’s picture

Issue summary: View changes

I could change the order of the pages attached to the guide. What I could not do is make https://www.drupal.org/docs/8/testing/types-of-tests-in-drupal-8 actually live.

hansfn’s picture

https://www.drupal.org/docs/8/testing lacks a maintainer. I guess you (alexpott) or xjm could take that role.

I tested the "become maintainer link, but I didn't see the "Suggest improvements" field. Do you?

xjm’s picture

@hansfn, I unfortunately cannot commit to being a maintainer for a section of the handbook, because I am a Drupal core committer. That's already the most maintainership I can manage. I would imagine alexpott has similar limitations on commitments as he is also a Drupal core committer.

It's also not a solution to the problems described, unfortunately. This is not just about the PHPUnit docs; it's about the whole handbook. Adding a maintainer for one section of the handbook does not resolves that this is a problem for most sections of the Drupal 8 handbook. Thousands of hours across the community were spent creating content prior to Drupal 8's release, content that is now practically unusable. We can't just say that the solution is for dozens or hundreds of volunteers to step up and reorganize and rewrite content that is broken.

hansfn’s picture

@xjm, it was just suggested as a short (to medium) term solution to the problem of getting that specific part published. And I really wondered if alex or you did see the "Suggest improvements" field ;-) It's obviously not a solution to the whole problem/mess. (There are a lot of issue with the migration.)

xjm’s picture

Another example is the update/migrate documentation. Gábor Hojtsy spent many, many hours before release working on the section of the handbook that the canonical typeable URL http://drupal.org/upgrade linked to from a text file in every Drupal core version across major releases as long as I know. Now it redirects to this: https://www.drupal.org/updating-and-upgrading-drupal-core

That page is not really helpful at all, a lot of words that don't show me what I need to know. Resources that send me off to strange places. It has a content header in the right sidebar of "Upgrade to Drupal 7" which is definitely not I want.

Similarly, http://drupal.org/upgrade/migrate redirects me to https://www.drupal.org/docs/8/upgrade/brief-overview-and-history-of-auto.... That is another pretty unhelpful page and a lot of content above the fold has replaced carefully crafted content on Migrate in D8.

Landing on either of these pages, I am completely overwhelmed and can't even start finding the information that I'm being told to find from official files in Drupal core itself. None of the content is really useful and it is definitely not what was intentionally linked when the documentation was referenced. This is a critical regression of lots of Drupal.org content.

xjm’s picture

Thanks @hansfn. I don't see anything called "Suggest improvements." Arguably, Drupal core committers should be granted whatever role is needed in the new content model to have full permissions on any page, because if we're trusted enough to put code on hundreds of thousands of sites we should probably be trusted with also making the changes to any section of handbook. It affects many more users than just the handful of core committers though. Hundreds of users contributed to this documentation.

Before, anyone could contribute and help maintain the handbook whenever they had a problem. I understand the goal of switching to a curation model, but it also means hundreds of people who might have helped no longer can, and even granting them permission does not solve the underlying problem that the handbook has just been really, really messed up in the past year.

Anonymous’s picture

tvn’s picture

Regarding the urls, here is related issue #2824046: Plan for URLs for core modules documentation.

I also agree re: giving full permissions to core maintainers on any docs page. Right now there is no role that could do that, we have a story in the backlog to give that permission to all advanced roles such as webmaster.

xjm’s picture

In #2845731: Theming guide links are wrong we converted to the Drupal 8-specific link and #2841696: References to d.o/cron, which is documentation for Drupal 7 has started to do so as well. But this is a bandaid on the problem. These documentation links are unmaintainable when they are split up for 7 and 8 in this way. Do we have to update every link in core every time we branch a new major? Is 8 supposed to mean 8-plus? Why do we default to D7?

The structure problem also needs solving. A generic link instead of version-specific still will not help if the section it links to is unordered and disorganized.

NonProfit’s picture

xjm,

Good point. I'm now maintainer of https://www.drupal.org/docs/8/core/modules, so if there is any way to better structure this guide, please let me know.

eojthebrave’s picture

It seems like there are quite a few different things to address in this issue, and that it might help to try and break things up a little bit in order to deal with them each individually.

Anyway, here are my thoughts on at least some of them. :)

There are definitely some issues with the permissions setup that is making it challenging to edit and contribute to documentation. I've been running into this too. I think the best way to get these addressed right now is to make sure the DA team is aware of them, and that we're suggesting viable alternatives to the current setup, so that they can help get them fixed. These issues probably mostly belong in this project https://www.drupal.org/project/drupalorg, and that the permissions specifically are already being discussed here #2860875: Permissions plan for Documentation Guide and Page content.

Significant sections of the handbook for D8 are just missing.

I think this is less a result of the migration, and more that either didn't exist for D8, or if it did it was a mostly D7 page with a note about D8 changes on it. If content is missing we should open an issue to get the content documented and added. There are at least a handful of issues related this already. Example: #2774809: Write documentation for Drupal 8. Another way to at least start looking at this would be to compare the D7 and D8 sections and see what's missing.

alexpott also reported that "guide" pages' limit of 1000 characters (apparently) was insufficient to provide sufficient context for the child content ...

My understanding is that based on the content strategy/design work that was done these guide descriptions should be short and succinct. Which is probably why this was set to 1000. But, if that's not enough space I'm sure it can be made longer. Though I would argue we should still keep it relatively restrictive to encourage shorter descriptions and prevent people from just cramming a bunch of text into a space that's intended to act more as a navigational aid than content. It also looks like perhaps this change was made post initial migration, hence the weirdness with pages that currently have a description longer than the allowed value.

Should we maybe open a separate issue to address this?

Another example is the update/migrate documentation. Gábor Hojtsy spent many, many hours before release working on the section of the handbook that the canonical typeable URL http://drupal.org/upgrade linked to from a text file in every Drupal core version across major releases as long as I know. Now it redirects to this: https://www.drupal.org/updating-and-upgrading-drupal-core

That page is not really helpful at all, a lot of words that don't show me what I need to know. Resources that send me off to strange places. It has a content header in the right sidebar of "Upgrade to Drupal 7" which is definitely not I want.

This is just the result of someone(s) making edits to that page. And not of the migration. Checkout the revision history. We might want to consider rolling this back to a previous version of the page, or at least sort out the edits that where made and "fix" things. Example of a maybe good revision to compare too https://www.drupal.org/node/496/revisions/9538797/view

These documentation links are unmaintainable when they are split up for 7 and 8 in this way. Do we have to update every link in core every time we branch a new major? Is 8 supposed to mean 8-plus? Why do we default to D7?

I don't know why the default is Drupal 7. I vaguely remember this conversation happening at some point in the past, but I can't dig anything up. :/

Regarding updates to links in core for every major version, I think the answer is, it depends. We know, based on feedback and testing, that people really wanted the documentation to be split by version. And NOT have single monolithic pages that cover every version of Drupal. This alone is going to mean that for at least some things the answer is yes. The link is going to change. And should, because the content is different. The link to the help for the D8 version of a module should be different than the link to the D9 version for example.

There are however probably also going to be things like setting up cron maybe? Docs about release cycles, etc. Where the documentation is generic between versions and we should have a place for those to live, and those links aren't going to need to change.

wturrell’s picture

I think it would really help to get hold of a list of all current canonical drupal.org aliases (e.g. /upgrade) - from that we can look to see where each is used, and discuss if they make sense. [Edit: I'm aware we've scanned D8 core for links in #2855175, but can we generate it from the Drupal.org end?]

Also, do we/do we no longer have a place for non-version specific content, i.e. under /docs rather than /docs/7, /docs/8 etc.?

e.g. /glossary currently redirects to /docs/7/understanding-drupal/glossary, yet we've already begun mentioning D8 terms and IMHO this is one case where maintaining multiple editions of a page is asking for trouble (for both those updating and using it).

@eojthebrave mentioned how developers like documentation split by version. I agree, but for me it only starts being of significant use when most URLs are neatly mapped (e.g. in Laravel, where you can change the major/minor version number but leave the rest of the address intact and still be fairly confident you won't get a 404). Could we make things easier for people by linking to earlier/later versions of content from the sidebar?