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.The tabbed section navigation at http://drupal.org/documentation could use some work. Above all else, navigation needs to act consistently. We have a couple problems:
- We are moving to each subsite having its own header, like https://association.drupal.org/, so the API tab should go. There is a link in the footer, and under Developer guides at http://drupal.org/documentation. Is that enough, or should it be added to the sidebar on some pages?
- Recently updated goes to a completely different section of the site. It should go, or be taken out of the other section.
This could leave the documentation section with no subsections. I think it might be good to use books linked to from http://drupal.org/documentation as sections. This would be a good time to add breadcrumbs between the book and specific page, although that is kinda redundant with the book hierarchy block.
| Comment | File | Size | Author |
|---|---|---|---|
| #18 | 1392196-docs-nav.patch | 2.27 KB | jhodgdon |
Comments
Comment #1
jhodgdonadding tag
Comment #2
drummhttp://drupal.org/getting-involved-guide is under documentation, but its subpages are under community. It would be under community, but setting a URL alias on the page caused drupalorg_crosssite to miss it. I think they all belong under community.
This needs to be verified, but I think the check for
drupalorg_crosssite_menu_path('main', '^(documentation|handbook)(/|$)'))seems redundant withdrupalorg_crosssite_menu_type('main', array('book'))in documentation's nav_content_links. Everything aliased to documentation* and handbook* is likely a book node.Comment #3
drummAnd #1278256: Develop a plan to make it more clear that the current Documentation on drupal.org is community maintained. proposes removing the section title, starting at the section tabs. I'd like to take a fresh look at that. In the original post here, I propose replacing the subsections. I think we need something to let people know they are in the documentation section of the site.
This should probably be tackled in a couple of phases. First, fix the bugs where sections don't work consistently, http://drupal.org/getting-involved-guide in #2 and Recently updated in the summary. Then bring in any new stuff and let API be its own site.
Comment #4
jhodgdonShouldn't it just be checking for the top-level book for book nodes?
I agree that the getting involved guide should be part of community.
Comment #5
jhodgdonsorry for crosspost, and I can't assign this back to you drumm :(
Comment #6
jhodgdonRegarding the Docs section, the next-level tabs make it clear you are in documentation (they say "Community Documentation"), which is why we didn't want the top-level Documentation header -- it's redundant.
Comment #7
jhodgdonI would also add that on most sites I have visited, this type of "what section am I in" is indicated by highlighting in the main nav, not by adding rows and rows of large headers to the page. Or via a small breadcrumb.
Comment #8
jhodgdonJust to reiterate (copy of what I put on the other issue)... The main goals with this design from #1278256: Develop a plan to make it more clear that the current Documentation on drupal.org is community maintained. are:
a) Don't use up extra space on every page with two rows of headers/tabs. We didn't think it was necessary to say "Documentation" as the section header, then "Community Documentation" below that in a tab.
b) Make sure it says "Community Documentation" prominently at the top, not just "Documentation".
I don't think we care whether the "Community Documentation" text is a tab or some large text, as long as it says "Community Documentation" and it's at the top. And if we have to have a section header saying Documentation still, for consistency with the rest of the d.o site, that's OK (though it seems to waste space).
Oh and we probably don't need the Recently Updated tab necessarily either (we have other and better ways to get to that information)... maybe just get rid of the tabs and make the section header say Community Documentation?
Comment #9
drummComment #10
jhodgdonOK, let's give this some more thought...
a) http://drupal.org/getting-involved-guide should definitely be part of Community not Documentation.
Actually, a few months back, Lisa Rex made this helpful list of the top-level books:
http://drupal.org/node/1168704
I think that the cross-site module should use the book ID to determine what section a page is in. Only the books listed on that page as being part of Docs should be part of Docs. The others are either part of About, Community, or another section.
b) Tabs in the Documentation section... The idea of having the API site and the Recently Updated page be the tabs was from the original re-design for drupal.org -- it wasn't something that the Docs team was necessarily behind or in agreement with (actually I think there were some other ideas for tabs that never had any code behind them and were dropped, like an alphabetical index I think).
So let's think about this... We currently have 10 top-level books under Documentation, and they mostly have long-ish names, so I don't think we can make all of them tabs...
If we eventually have the "Curated Docs" area, we'll probably want to have a "Community Docs" tab and a "Curated Docs" tab. It seems to me that having an "API Reference" tab then would also make sense (I realize it's on a separate site, but that's kind of arbitrary anyway IMO and might not be obvious to new visitors where to find it). Eventually we might also want to have a link to an external docs index (Lin Clark is working on developing this) as a tab too.
But for now, I don't think we need tabs.
And the Recently Updated page can definitely go. We have a much more useful page at documentation/manage that we point people to instead to get a handle on what is going on in docs. Actually, we can probably just delete that page entirely and put in a redirect to documentation/manage. Thoughts?
Comment #11
drummI committed the first bit of this, fixing http://drupal.org/getting-involved-guide, http://drupal.org/commitlog/commit/4364/6ad6eadd968153553c9f0dfeff9aa0b6...
(I haven't read the rest of the issue at this time, just wanted to get the straightforward part out of the way. We probably need an issue summary.)
Comment #12
drummFor Recently Updated, I went ahead and removed that tab, http://drupal.org/commitlog/commit/4364/45f62d3194fb4ea2eee36925b142a6bb.... The page still exists, I filed #1405438: Remove Recent updates page? to see about deleting it.
That fixes everything I'd consider a bug here. Now is a good time to consider what to do next. 10 long names won't work, the section tabs just don't handle overflow. I don't think we want Curated and Community, average people just want to find documentation, not figure out our community organization (I do like other cues like the new sidebar). I can't think of anything better than nothing at this point.
Technically, the closest thing we have to "is in a book" is drupalorg_crosssite_child_of(), which checks the breadcrumb and current path. I added it well after the buildout of the module, so there are probably places it could be used to clean up the code. I think I'll keep other cleanup in #1386716: Clean up crosssite module, which should not affect any UI if done well.
Comment #13
drummSince the redesign was mentioned, here is a rant: The old tabs were likely not heavily considered as part of the redesign design process. The brief was just for one site, not including subsites. During implementation, we interpreted it as heavily sharing navigation between sites, not knowing it hadn't been thought out that way. The redesign focused on areas of the site for outsiders; API was probably something they found important, but I don't think much time was able to be spent understanding docs. Nothing against docs or subsites, just lack of time on a huge design project. None of it takes into account changes since the redesign was designed. The site is ours to manage, this part is certainly ready for change.
Comment #14
jhodgdonIf we do want tabs for Documentation, I think that rather than building them automatically, we should consciously choose maybe three important items to have as tabs. For instance, right now we could choose:
Docs Home
Installation
and leave it at that. (That would remove API from the current tabs, and api.drupal.org is already listed as a link on Docs Home, so I think that is OK.)
Then if we ever are able to build the Curated Docs section, I think we'll be using it to build an official "User Manual". In which case, that would be added to the tabs.
Comment #15
drummI do like the strategy from #14, that matches what we do for some big topics under http://drupal.org/getting-involved-guide.
I filed #1408622: Primary links for API.drupal.org to get the API site standing on its own, which let's it get taken out of the Community Documentation tabs.
Comment #16
jhodgdonI posted on groups.drupal.org asking for feedback on this and a couple of other docs infra issues -- maybe someone will have a better idea of what in particular should be in those tabs, along the lines of the general strategy of #14.
If we don't hear any better ideas though, I think we can go ahead and go with #14 for now. It's not like we can't change it. Would it make sense to put these tabs into the admin UI menu system rather than hard-coding in the cross-site module, by the way?
Comment #17
jhodgdonWell, no one seems to have cared enough to comment here. So, here's a concrete proposal.
We have just these tabs under Documentation (for now):
Community Documentation Home (http://drupal.org/documentation)
Installation Guide (http://drupal.org/documentation/install)
Administration Guide (http://drupal.org/documentation/administer)
I think these are the most useful links.
Comment #18
jhodgdonHere's a patch that sets up this navigation. There might be a more elegant way to do it, but this one works... You can see it in action on pages like these:
(in install guide) http://docs-manage-drupal.redesign.devdrupal.org/documentation/install/d...
(in admin guide) http://docs-manage-drupal.redesign.devdrupal.org/getting-started/6/admin...
(in neither) http://docs-manage-drupal.redesign.devdrupal.org/node/1241116
Comment #19
jhodgdontagging for deployment
Comment #20
drummCommitted a simplified version.
Comment #21
drummUntag
Comment #22
jhodgdonThanks! It seems to be working fine.