Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.To promote discoverability of documentation pages, documentation guides should display two levels of content.
| Comment | File | Size | Author |
|---|---|---|---|
| #14 | bluecheese-2992858-14.patch | 1017 bytes | grasmash |
| #13 | Documentation___Drupal_org.png | 201.62 KB | grasmash |
| #5 | Drupal_8_Documentation___docinitiative_drupal_dev.png | 73.56 KB | grasmash |
| #4 | Drupal_8___Drupal_8_guide_on_docinitiative_drupal_dev.png | 84.06 KB | grasmash |
| #4 | Drupal_8___Drupal_8_guide_on_Drupal_org.png | 91.36 KB | grasmash |
Comments
Comment #2
hestenetHm - this makes sense for the very top level of the documentation page - but I'm not sure it makes so much sense for guides themselves.
There was a lot of user research done on the old books hierarchy that said that multiple nesting levels made discoverability much harder. It was a deliberate choice to enforce a flat hierarchy one level deep inside a given guide.
Comment #3
grasmash CreditAttribution: grasmash at Acquia commentedComment #4
grasmash CreditAttribution: grasmash at Acquia commented@hestenet I think you misunderstand. There is already a potentially infinite number of levels of docs. There is a restriction on nesting menu items, but it's easily worked around using entity references that create guides within guides within guides. I'd love to enforce a flatter hierarchy. But, that's a separate issue.
This issue is about exposing in the UI the guides and pages that already exist. For instance, listing all sub guides and pages that belong to the Drupal 8 Community Guide. It's is only a visual change and it only appears where it is applicable.
This change is arguably one of the most important for improving UX. At present, for the Drupal 8 Community Guide, you’d need to open 32 separate guide pages just to learn what pages the child guides contain. That’s not to mention the grandchild guides and so forth.
I'm all for flattening documentation by placing nesting level restrictions, but I don't think we should hide what's there.
See screen shot for the delta.
Comment #5
grasmash CreditAttribution: grasmash at Acquia commentedThis also enables us to show guide contents in panel panes:
Comment #6
grasmash CreditAttribution: grasmash at Acquia commentedThese changes have been approved by @eojthebrave and by the UX team during the open community meeting.
Comment #7
eojthebraveI like this because even though it doesn't address the fact that you can nest things to any arbitrary level it makes any individual landing page appear a bit flatter. e.g.) You get a longer, easier to scan, list of content below whatever point you happen to be at currently. Which hopefully makes it quicker to find the things you're after.
I believe this is at least part of why people in general like docs to have a flatter hierarchy. People would rather have pages with a bit list of links they can scan and parse on their own vs. having to click down ... down ... down ... to uncover the fact that this particular section doesn't even contain what they are looking for.
Comment #9
drummThis has been deployed with various fixes:
.left-contentstyles.og_menu_get_group_menus()once. To keep page load times from getting much higher.Comment #10
hansfn CreditAttribution: hansfn commentedGreat! https://www.drupal.org/docs/8 and https://www.drupal.org/docs/7 are so much more helpful now.
Comment #11
grasmash CreditAttribution: grasmash at Acquia commented@drumm It doesn't seem like this feature change has taken effect:
I'm not able to add these panes to the section nodes. They're not listed in the available content.
Comment #12
drummLet’s handle those in #2828874: Design top level landing page for the new documentation system, #2979204: Update bluecheese stlyes and allowed panelizer content for new docs designs or a separate issue. I think the idea was adding those to the top-level page(s?) only, but there wasn’t anything in this issue explaining the change.
Comment #13
grasmash CreditAttribution: grasmash at Acquia commentedThe CSS modifications to the patch make it such that the OG Menu blocks in #2994397: Allow top-level guide menus to be added to sections do not correctly render as two column when inserted into section nodes.
On the dev site, the /documentation landing page looks like this:
But on prod, it looks like this:
I suspect this is due to the changes in SASS nesting.
Comment #14
grasmash CreditAttribution: grasmash at Acquia commentedAdding patch to address two column menus on page and section nodes.
Comment #15
drummThis was cleaned up and deployed. Only one small change to reduce negative margins, which are often not ideal.
The commit didn’t show up on the issue here because the issue was on the wrong project.