This is part of #1278256: Develop a plan to make it more clear that the current Documentation on is community maintained.. Original statement: "In the process of making docs clearer they are community-maintained, we decided we should have some kind of new navigation (maybe)."

Contents of this issue


This issue concerns improving the features d.o offers to users (and maintainers) to discover, explore and move among the documentation pages. These existing and proposed features include:

  • Doc page nav: The navigation features on individual pages. Currently a list of child pages within the content body, and an abbreviated non-interactive tree in the right column.
  • Search: d.o's search, and google/bing etc
  • Tags, tag search
  • Doc map: Stand-alone page with complete table-of-contents tree (not currently implemented)


The overall set of "navigation" features should support the following activities, and make them faster, easier, and/or more possible than they are now:

  • Find documentation again that you have seen before
  • "Find documentation on a topic": This could be supported through search (both on-site, and google etc) and navigating through the book outlines.
  • Find a place to put information: If you have some information that you want to get into the documentation, you need to find where it should go (on an existing page, or as a child of an existing page). This is similar to finding information on a particular topic, but not necessarily the same, since presumably you are talking about a more experienced user who has read the docs before. They still would either use search or hierarchy navigation to find the docs they have seen before.
  • "Understand and explore the conceptual and documentation landscape":. (Loosely: "Browsing") Provide the user the ability to comprehend the broad expanse of all topics, and the scope and organization of the documentation that covers those topics. Allow the user to progressively reveal finer-level concepts, while, to the extent possible, retaining in view the larger context. Beyond ordinary readers, doc maintainers need the same facility to be able assess and maintain the documentation structure.
    • If the complete doc landscape is too large or slow to present on each individual doc page, then some additional "doc map" page(s) could be provided to serve this purpose.
  • For each doc page: "Where am I?", "Go nearby" and "continue reading": From each doc page, allow the user to know where they are, and to proceed incrementally through the docs to conceptually nearby or sequential pages:
    • Show location within hierarchy (links to ancestors)
    • Links to subsidiary pages that explain more details.
    • Links to broader pages that put the current page into context.
    • Links to preceding pages that introduce topics used on the current page
    • Links to succeeding pages that follow on from the current page
  • "Find related pages, elsewhere in the hierarchy" . Suggest pages covering related topics
    • Could be implemented via specific links in the content (as now)
    • Could use keyword tags [which we have, but pages are not widely tagged with keywords]


  • Visual design: Amount of space used on page
  • Usability:
    • Obviousness without explanation
    • How much clicking and scrolling required
  • Accessibility: people with vision/mobility limitations must also be able to use the navigation
  • Performance
    • Bandwidth required
    • Computation required in client browser
  • Implementation difficulty level (and likelihood)

Candidate alternatives and examples

Most of the suggestions to date are for alternative navigation widgets for doc pages. These are all listed below, with screenshots. In general, these alternatives vary along a number of dimensions:

  • Choice of how many pages are shown, and which ones.
  • Interactivity (expand/collapse)
  • Browsability (Does widget show all pages?)
  • Scalability (Even if a mock-up is attractive, can it handle a collection the size of d.o docs?)
  • Use of space on the page
  • Performance
  • Implementation effort required

Table of alternatives and their characteristics

Current docs navigation

Plone-style menu

#19, #75, #77, #93, #100

Displays a dropdown list of page titles, using dotted numbers (like 3.5.2) to indicate hierarchy.  Displays the entire hierarchy of this site (169 pages) -- not so practical for 8000 pages. In addition, this navigator is supplemented by a link to a doc containing the entire site as a single document (~400k).

Mega dropdown

"Tidy collapsed menu"

References: #32, #96, #120:
Live example at open atrium docs:
Hybrid between list and tree. Initially displays list of top-level items. Clicking on an item's [+] will hide the other items at that level, change the single selected item into a "header", and reveal its children. User can continue to drill down by clicking on the children's [+], or zoom out by clicking on any level of header. (Bug/inconsistency: clicking on the lowest header actually navigates the browser to the associated hyperlink, instead of collapsing the tree.) Browsability note: Because only one list of siblings appears at a time, user loses most of
existing context on each click.

Scrolling list box

Reference: #114

"How about a scrolling list box (like a multiple-select box) with a "Go" button for navigation? It could have just a few elements in it, and wouldn't drop down." Not specified in author's proposal which pages to display in the listbox, or whether any hierarchy would be shown. Need more detail.

MSDN-style menu

MSDN gives three different options for navigation, which can be selected via the "options" (gear icon) menu.

  • Classic:
  • Lightweight: Displays a non-interactive "outline" view of the contents, which displays only the current page's ancestors and children. No siblings of the current page, nor siblings of ancestors.
  • ScriptFree: Displays a column divided vertically into three areas:
    • List of ancestors
    • List of children
    • List of peers


Expandable tree able to show the entire hierarchy of MSDN docs. Clicked branches retrieve data for children via Ajax.


Displays a non-interactive "outline" view of the contents, which displays only the current page's ancestors and children. No siblings of the current page, nor siblings of ancestors.


Displays a column divided vertically into three areas:

  • List of ancestors
  • List of children
  • List of peers

#117 probably refers to the Lightweight mode of MSDN, and is mocked up as a drupal version in the screenshot below, though this mockup actually includes siblings of the current page's great-great-grandparents (children of the book's top level), which MSDN-Lightweight does not.

Stand-alone Documentation Map page

This proposal envisions a separate page which presents an expandable/collapsible tree of the complete documentation hierarchy. The main aim of this complete is to provide the support for "Understand and explore the conceptual and documentation landscape".

By being a separate page, it can afford the bandwidth and delay entailed by the large amount of data required for the whole tree. In concept, this is very similar to MSDN-Classic's tree.

Prototypes, using actual d.o data:

No navigation

#120 This does not attempt to support any of the objectives listed in the requirements, but does fully satisfy the constraints on space, performance and implementation

Proposed Resolution

So far, we have reached consensus that we would like to adopt a "MSDN Classic" navigation. This should help with several of the uses above (finding information by navigating through the hierarchy, and understanding the landscape). There's now a separate issue for figuring this out:
#1508832: Support +/- expand/contract in Book navigation on

Still to be resolved: Can we also do something to help with:

  • search
  • find related information in other places
  • understand the overall picture


jhodgdon’s picture

issue summary updated to point to new mockup

jhodgdon’s picture

Issue tags:+docs infrastructure

Adding new tag. These issues tend to get moved to other issue queues, so we need a unifying tag in order to find them consistently.

arianek’s picture


arianek’s picture

Issue summary:View changes

new mockup link

jhodgdon’s picture

Title:New navigation block for books» New navigation for d.o community docs
wfx’s picture


wfx’s picture

Issue summary:View changes

new issue summary since we haven't decided after all

dasjo’s picture

jhodgdon’s picture

Check out these mockups that Kristof just posted for their multiple-outlines ideas:

jhodgdon’s picture

Issue tags:+valid issue

Tagging so it doesn't get picked up by #1421874: [meta] Documentation Issue Queue Cleanup

gwideman’s picture

I would draw attention to there being (at least) two related needs to be served:

  • Allowing users to step from one page to conceptually nearby pages up, down, and across the hierarchy.
  • Presenting to users (and authors and maintainers) a way to browse and understand a conceptual landscape consisting of thousands of pages (as they might get oriented to a paper book by looking at the table-of-contents).

One tool that advances both of these objectives is a collapsible tree view, which is often used for site navigation. MSDN Library (as mentioned in #117 in the summary above) has a particularly extensive example: (and choose "Classic" view, if that's not the default.)

To demonstrate the utility, I created a demo showing's entire doc hierarchy as a collapsible tree: (look at the "Key to symbols" section for what is clickable: icons in addition to the [++] and [--].)

Now, individual pages could not afford the load and crunching time to use the entire tree for their nav. One could imagine a version of Book implementing a speedier Ajax-fied version of this.

Meanwhile, depending on whether others find the complete tree view as powerful as I do, it is something that might be implemented as a separate "complete docs map" page. That has the prospect of making more powerful docs exploration available, while taking pressure off the Book apparatus as the only solution.

That said, I don't feel I've thoroughly looked yet to see who's been down this path before before inventing wheels.

jhodgdon’s picture

I think this should be the next Community Docs infrastructure priority.

What needs to be done:

a) Decide on what the best navigation for the right sidebar of Docs pages should be. I think the 5 choices in the issue summary are representative, but if we need more choices to consider (not sure if #9 falls in that list or not?), let's get them added to the summary.

b) Build and deploy the best choice.

Any opinions from anyone on (a)?

gwideman: interested in being the developer for (b)? :)

jhodgdon’s picture

Actually a great next step would be for someone to edit the issue summary and put in better descriptions and/or images of the alternatives. Any takers?

gwideman’s picture

jhodgdon: By way of a quick response: I'm actively consolidating some thinking about this, and will be back with more discussion in a couple of days. If the issue summary hasn't been tackled by then, I'll have a go.

jhodgdon’s picture

Sounds good, thanks!

arianek’s picture

I reaaaaaaaaaaaaaaaaaaally like the example in #9 on the sandbox site! It achieves 2 things - keeping the sidebar somewhat condensed on first page load (though of course not as much as a dropdown), and also allowing people to easily browse through the book menu *without* having to actually navigate to all the pages. I think this would be a significant improvement to what we have now, and a less drastic (and hence less controversial) change.

gwideman’s picture

@arianek: Thanks for the positive feedback. I can't tell if you noted that I'm not advocating this be used on every book page, for reasons of performance, page-real-estate and likely implementation-effort. A slimmed down version possibly.

But I am much more interested in the full-featured version, implemented as a stand-alone page, which I suspect is more tractable to implement, technically and within d.o.'s situation.

I discuss what I think are the requirements in play here, with my suggestion and rationales:

@jhodgdon: I didn't get to actually revising the Issue Summary on this page. As just mentioned, I've written up my thoughts on the matter on my site. I hope this contributes to the discussion, but I don't want to just substitute my views for the existing Issue Summary as my version encompasses some different territory than the Issue Summary envisions.

That said, if no one in the next day or two at least tackles getting some screenshots for the Issues Summary, I will do that.

jhodgdon’s picture

Great -- if you have time to make a real Issue Summary, which summarizes the ideas presented thus far (including yours), that would be very helpful.

I see what you're saying about the collapsible "index to everything" being a stand-alone page. Let's get that idea (with a screen shot and a link) into the issue summary too. It would still be nice if we could have expand/collapse on the right sidebar somehow too, but yes that whole index takes too long to load to be practical for the sidebar, alas!

gwideman’s picture

jhodgdon: On looking at editing the issue, I noticed that adding an image calls for a URL, so I'm guessing I need to upload images as a separate step... I don't see a way to upload, or add attachments, during the issue editing process, so perhaps I need additional powers? However, I do see a way to add an attachment to a comment (like this one)... is that what one is supposed to do?

-- Graham

jhodgdon’s picture

Yes, I think you would need to upload the images on a comment, and then you can grab their URLs to use in the issue summary.

gwideman’s picture

Uploading images for revised Issue Summary

gwideman’s picture

Issue summary:View changes

moved list of options from parent issue to this one.

jhodgdon’s picture

Wow, gwideman -- thanks for the incredibly detailed issue summary! Let's discuss it at docs office hours today (in about 4.5 hours).

jhodgdon’s picture

Issue summary:View changes

Added: Requirements; Table of characteristics of alternatives; screencaps for proposed alternatives.

Itangalo’s picture

gwideman++ for a great summary.

My five cents on this is that MSDN-classic seems like the best option (as the summary table describes), as long as we don't find any new innovative way of browsing the docs. Gonna think some more on it, and try to be innovative.

linclark’s picture

new139.22 KB

Here is an image that shows the current docs structure. The headers across the top are the top-level handbooks and the layers underneath are the levels within that handbook and the number of pages at each level.

nmudgal’s picture

Or may be we can have mixture of search + menu like this:
putting search like this on top of menu [ search type entitled ' Support'] & having menu bar like this which looks more decent with all '+-' things than just msdn classic menu [ see in rightsidebar]
this can have an impact on performance but don't think it will be big.

Just a thought!

jhodgdon’s picture

We had an IRC meeting about this today in the #drupal-docs channel. Highlights:

1. There are several pain points or objectives for navigation:
a) Find information about a topic you are interested in
b) Find a place to put information when you're ready to write/edit documentation
c) Find related information once you have read one page
d) Understand the docs outline as a whole

2. For each of these, we want to make it easier, faster, and/or possible

3. We all agreed that we would like to adopt something like the "MSDN Classic" navigation. This would be much like the current d.o nav, but it would have a click-to-expand/collapse feature on all of the levels of the tree. This would allow you to find a page of interest without incurring tons of page loads, so it would help with ease/speed in objectives (a) and (b), and maybe (d). It wouldn't really improve the current nav for (c), since you can already see the parent/sibling/child pages in the current navigation. It would just make it faster to navigate down through the hierarchy. Possible refinements/features:
- a search box that would let you expand pages based on title matching throughout the tree, or maybe show how many hits are down each branch of the tree
- degrade to current nav (essentially) if person does not have JavaScript
- show number of pages (direct children? total descendents? both?) next to the page title (so you know how many you'll see if you expand) [that would help in (d)]
- show number of comments along with the title
- show the page size in KB.
- must be intuitive from the start what all the numbers etc. mean if it is going on the right nav

4. We still need to do something more about item (a)... Right now, all you can do for search is use Google, or you can use d.o search and limit to book pages. Ideas:
- d.o search filter on top-level book: might not be too helpful - it isn't always obvious which book the information you seek would be inside.
- d.o search filter on d.o project: this has been discussed; wouln't be helpful for finding help on things like the Core Blocks functionality, but would be useful for finding help on using particular non-core modules.

5. We also still need to do something about item (c)... Right now we have a Keywords field, which will be more helpful as it gets filled in. That would let you click on a keyword and find other pages related to that keyword. Another idea would be to allow for multiple outlines, which would allow you to navigate in different outlines for different purposes, and see what other pages have been put together in other outlines. Another idea would be to add a nodereference "related pages" field, which would allow you to make links to pages in other locations [sort of "multiple outlines light"]... This wouldn't be as good as multiple outlines, but it might be easier to accomplish.

damien_vancouver’s picture

My vote is for the MSDN classic too, and also with some kind of linked search textbox above it which allows searching the tree somehow, if that's feasible.

Here's my attempt at documenting the use cases of docs navigation and different pain points for the docs navigation. I'm sure I've left some out.

Use Cases

"End User" and General Use Cases

1) Searching for instructions for a specific task but not sure of module (e.g. "how do I <something> with Drupal")

2) Searching for instructions on how to use a specific feature/module/functionality (e.g. "export view to CSV file")

3) Searching for introductory documentation/tutorials (e.g. "Adding new users")

4) Contributing to community docs by expanding an existing section or adding a new section

"Site Builder / Developer" Use Cases

5) Searching for a configuration recipe on how to build something (e.g. "Create a mailing list")

6) Looking for additional module documentation or examples (e.g. "display suite hide field label")

"Docs Maintainer" Use Cases

Could someone suggest more?

7) Managing / Reviewing page structure

8) Merging duplicate or related content

Pain Points

A) Locating content when you're not sure of the right keywords. Visual inspection of the tree is too slow, with all the page reloads, and inability to see how the tree is organized. (1,3,7,8).

B) Docs search results are not obvious enough on google. Try a google search for "drupal add new user". It would be nice if the best answer "Tutorial 14: Create a new user" was more prominent among the other results (somehow) (meta tags or something to help google out?) (1,3,4,5)

C) It's confusing when results are from older Drupal versions only. (e.g. from documentation page, click on "administration guide", then "managing users", but there is no Drupal 7 section, only Drupal 6 sections. The Drupal 6 section is almost totally accurate though, so is "the best" we have to offer. But an end user won't know that. Solving this one is probably better done by enforcing a style guide (don't make things version specific so they can be updated) rather than navigation. (1,2,3,5,6)

D) The "Search" box in the top right is not limited to documentation so is probably useless for someone searching for docs. (e.g. Visit, click "documentation", read list of titles, don't know where to go, type "add new users" into search box). (1,2,3)

E) The Site Building Guide is full of multiple branches of content that are hard to explore. Information is organized by module, under HowTo's, under the individual tutorial trees, and under Site Recipies. It's currently very hard to navigate to the best spot, since each change of tree branch reloads the page and your old location (and its siblings) are lost. (1,2,3,4,5,6)

F) Contributing: Finding related content / convincing yourself you're doing it in the right spot. It's hard to know whether to create a new page or edit an existing one - especially when you find similar content in two different branches of the tree. (e.g. say I want to now add/update the "add a user" instructions for Drupal 7, having just figured it out. Do I add a new "User management in Drupal 7" page, or update the "User Management in Drupal 6" page? Any kind of novice user will likely just end up doing nothing rather than do the wrong thing. (4)

Pain Points Addressed by the current proposal

The current plan with the MSDN classic type tree on the right solves or helps out A, E, and F. If we add some kind of keyword search to the tree, then we have improved D as well as doing a nice job of A and E.

B and C are not addressed. B is out of scope. C we could maybe implement with some kind of faceted search capability on top of our search box, but I recommend we just get out of the habit of making things too version specific (like the "adding new users in Drupal 6" example), and it would work itself out.

gwideman’s picture

damien: I like your initiative to enumerate some use cases. On the end-user list, I note that 1,2,3 are all "how to do something" topics, and 4 is end-user-as-contributor.

I would add that another end-user need is simply to understand the "what" of drupal: Gaining an understanding of what is drupal's structure: what are its components, what are their functional relationships, and how do components and functions map onto the artifacts that are easily inspected, such as the file layout and the database structure.

I raise this, because this type of info is often complementary to, but not subsidiary to, the task-oriented docs ("orthogonal" on might say). A user may hunt for it as a quest in itself, or as reinforcing info while conducting a task.

gwideman’s picture

Here is the data on number of pages at different levels of the hierarchy, by book (similar data to that posted by lin. Mine is from 2012-03-12 or so). This is useful for assessing the typical size and depth of the tree widget as users wrangle it to navigate around the docs. So, for example, for the Site Building Guide they'll spend a lot of time exploring at the 4th to 7th levels.

The plots are sorted in order of total pages in the book (biggest first). The plots are separately scaled so their peaks are at "4 units", with that value marked on the Y axis. In general, the more pages a book has, the more the peak is shifted "deeper". This is because individual pages tend to "fan out" to only a limited number of child pages, so a larger book tends to get deeper, rather than wider at each tier.

More stats at:

-- Graham

jhodgdon’s picture

Title:New navigation for d.o community docs» [meta] Improve search/navigation for d.o community docs

So... It seems like we have reached consensus on one concrete thing to do: make the right-sidbar nav look like it does now, but with the added ability to +/- expand/contract the hierarchy, so that you don't have to incur page loads to delve into the structure.

Accordingly, I'm going to move that concrete idea into its own issue, and make this a meta-issue about generically improving the search/navigation. I'll also update the issue summary.
#1508832: Support +/- expand/contract in Book navigation on
(Note: I found a module we can potentially use to do this! -- check out that issue)

jhodgdon’s picture

Issue summary:View changes

Added accessibility to constraints section and some other minor edits there

jhodgdon’s picture

Another idea:

Over on #1508216: Moderation report for Installation, sirtet suggested (comment #5) that we add breadcrumbs to Docs pages, which would show you where you are in the book navigation.

That might help?

damien_vancouver’s picture

I think breadcrumbs on docs pages is a great idea if we're going to have a tree that you can alter by pressing + and -. That way no matter where you explore to at the right, or how you transform that menu tree, the Breadcrumbs will tell you where your current page is.

I think they are a very intuitive navigation tool in their own right, that is not as overwhelming as the entire tree. They are especially handy when you land at a page via a search result. It's very easy to quickly broaden your focus a bit by moving up a few levels in the book hierarchy, and you can really do that with just a glance as the page loads.

arianek’s picture

I *would* support breadcrumbs, but I think they're going to bring disaster in the future. As soon as we get into using multiple book outlines, breadcrumbs will become a massively complicated maintenance burden - I think we're better off sticking with just the book nav block at the bottom of the page.

Itangalo’s picture

#31: That *is* a good point – well done to find it. (Otherwise: yes, breadcrumbs totally makes sense.)

jhodgdon’s picture

Yes, good point -- no breadcrumbs then.

I will go advocate on the "build expand/collapse nav" issue that the links in the "breadcrumb trail" are indicated with some kind of formatting (bold), which would accomplish much the same purpose of showing you where you are.

jhodgdon’s picture

mshaver recently posted
which suggests a different type of navigation. Any thoughts as to whether this has advantages over what we already decided to do?

damien_vancouver’s picture

I checked out the notebook navigation in OpenAtrium, and I quite like it, but have one major reservation. The like: It's basically a simplified version of a tree control that doesn't let you have two branches open at once, if I get it correctly? Playing around in it, I was able to figure out opening and closing the branch of the tree I was on, and therefore how to back up and find other branches.

The reservation: What concerns me is losing the ability to visualize portions of the tree at once. One of my major pain points on community docs pages anyway is figuring out what sections are available once locked into one branch of the tree. That goes for contributing and just exploring to read about stuff.

I think that would be harder with only one path able to be open at a time, as you're back to trying to remember. For example, choosing between sub-trees of "Contributed Modules - Contributed Module Documentaiton" vs "Howtos" vs "Site Recipes" vs other places still in the Site Builder docs would be easy with a tree that can be open to all three places to visually compare, but not with the admin approach. Because only one path is open at a time it would be just like it is now - you have to remember it / write it on a scrap of paper / have multiple tabs or windows.

jhodgdon’s picture

Damien: Thanks very much for testing and providing that thoughtful analysis! Barring any further input, I think we should probably go forward with our current "+/-" navigation idea then, since it contributes to the "visualize and understand" goal better than the notebook navigation.

Karll’s picture

Just curious if anything has spawned from here - I found that DHTML module will perform these functions but the module is buggy and not really being supported from what I can tell. On core 7.15 it will crash CKeditor if bullets are used.

jhodgdon’s picture

On this issue, we decided on navigation, and spawned a separate issue (which has so far gone nowhere):
#1508832: Support +/- expand/contract in Book navigation on

Crell’s picture

Issue summary:View changes

Add new section for proposed resolution, rearrange some of the requirements slightly, put links in TOC

jhodgdon’s picture

Issue summary:View changes
Issue tags:-valid issue+Usability