Created by: gwideman, Mar 20, 2012 4:51 am
Revised by: gwideman, Mar 20, 2012 7:54 am (8 revisions)


The notes on this page are prompted by the desire to improve the usability of the body of documentation at, specifically in the area of what is loosely known as "navigation". A related issue on is here: #1289090: New navigation for d.o community docs
In this page I:
  • develop some thoughts about what "better navigation" means in terms of distinct requirements.
  • I will call out "Table of Contents" as a distinct area of interest.
  • make a start at some ways forward for's doc usability
  • discuss some shortcomings of drupal's book module's idea of structure, which is somewhat at odds with some requirements for TOC and Nav.

Background's documentation currently consists of over 8000 web pages, almost entirely created within 16 hierarchical books (not including the docs). Drupal's book module, which is employed here, furnishes some basic features for creating and editing hierarchically organized pages, and presents them to users with some basic navigation aids. Some statistics about this body of documents may be found in my recent study.
Such a large body of pages would be challenging for a very sophisticated doc management system, which drupal's book system is not. Hence the collection of docs has become challenging for users to explore and find docs within, and also presents difficulties to doc maintainers trying to oversee and refine the collection's content and structure.
Beyond the technical question of how a book module might implement more sophisticated features for larger collections, there is the additional challenge that on there is only limited support for implementing far-reaching change to existing functionality. Proposed improvements stand more chance of implementation if they are of limited technical scope.


In my view, it is important to recognize three distinct sets of motivations a user might have, in the area under discussion:
  • "Go to specific topic": How do I find the page(s) on topic X?
  • "Go nearby": What can I click on to take me to conceptually nearby pages? "Nearby" pages would include pages covering subsidiary topics, or the next or previous page in a sequence.
  • "Understand the conceptual landscape": How do I comprehend the broad expanse of all topics, then progressively zoom in to finer-level concepts within the larger context? In a paper book, this activity is served by the Table of Contents -- It presents the "lay of the land" at progressively more detailed levels. (Beyond ordinary readers, doc maintainers have a parallel motivation: How do we cultivate and maintain the portrayal of the conceptual landscape?)
As's documentation is currently implemented, I estimate that:
  • "Go to specific topic" is most frequently and successfully achieved through search, either on-site, or via google et al.
  • "Go nearby" is served somewhat satisfactorily by the existing "book-navigation" (children, prev, next and up) and the "book-block-0" partial tree in the right column. (Not entirely satisfactorily: No way to see children of parents' siblings, which may be the most conceptually adjacent.).
  • "Understand the conceptual landscape"is almost completely unserved, because the current non-interactive "book-block-0" is so abbreviated compared to the full body of documents, and there is no other way to view the full tree. I contend that this severely dilutes the value that the existing doc content could be delivering. This is the area that I will address most extensively.
Of course these three motivations are not entirely separate. A reader needs an understanding of the conceptual landscape in order to consider tracking down docs on a specific topic. Or studying a specific topic may spark an interest in reading a related but not nearby topic, and so forth.

"Understand the conceptual landscape"

In the next section I will enumerate some requirements for a feature that serves the users' (and maintainers') need to "Understand the conceptual landscape".
As a concrete preview, my position is that the minimum feature set needed is an interactive tree view displaying the entire body of documentation, such as the one screen-capped below, and prototyped in my Drupal documentation trees example. (This is a work-in-progess as I refine the UI.)
My prototype d.o doc tree
MSDN navigation/toc

drupal-msdn-toc-classic01.PNGThe idea of having a complete tree for a large body of documentation is not particularly novel. For example, it is common in help systems, and is similar to the left-pane tree at MSDN. (Note, this is the "Classic" display, not the "Lightweight" display which abbreviates what is displayed in the tree like d.o.'s current right pane tree, and is similarly difficult to use. See MSDN's settings menu (gear icon).)
Once I elaborate the requirements, I will discuss some technical and organizational reasons why such a display is likely to be impractical as the navigation for individual documentation pages, but would have considerable merit as a separate page.

Requirements for "Understand the conceptual landscape"

The following table summarizes requirements I've accumulated so far for "Understand the conceptual landscape".
Top-level requirement
UX concept
Supported by feature

Allow entering and learning the documentation's conceptual landscape in a coarsest-to-finest manner
Must be able to start by seeing peer items adjacent to each other
compare and contrast
Interactive expand of tree control

...then drill into particular peer items
progressive disclosure

Browse by theme and discover docs by roaming the tree
Low effort but good visibility
  • Complete tree available
  • Fast response to expand/ collapse
  • Expand/collapse-all-descendants on any node

Give confidence that the display is exhaustive -- there are no hidden nooks or crannies to continue searching for.

finite search
Show the complete dataset (ie: all the pages) in the one tree

As context, make accessible whatever nodes the user thinks are helpful

rich/complete context
Tree contains and can show any and all nodes (contrary to current d.o docs, and also simplified msdn tree).

Keep user oriented to any significant structure/landmarks, eg: which book.

Help user orient to structure
Color-code nodes (colored icons).

Provide preview info about "what's below this node" and "what's at this page"
Support user decision to invest in:
  • Open a node?
  • Retrieve a page?
Enable user to make intelligent UX cost/benefit decisions
Some basic data at each node about how many subsidiary nodes, and date/size/comments-activity of linked page

Put some current topic in context of the entire body (and enable discovery of nearby topics).

Enable conceptual zoom in AND out.
If tree was part of each page, then tree could sync (open) to the node for the current page. If tree is on separate page, then something trickier is needed.

Search based on words in doc title

Info should be searchable!
Javascript search within nodes in tree. (Or browser search, but that searches only expanded/visible nodes.)

Note: UI improvements

As an aside, in various ways I am not satisfied with the current prototype tree view:
  • I think the data attached to each node is too visually noisy. I'd like to develop this into a tree-grid with the data in columns to the right.
  • Loading speed is a minor issue, and would be moreso with a tree-grid. That's prompted me to do some research into increasing performance.
  • I am considering some refinements to the icons.

Complete Tree: Feasible as separate page, not as on-page navigation?

So far as I can reason, the full TOC tree would not work as navigation for each page:
  • Basic dimensions of time and space:
    • To much data (about 1.7 Meg at the moment), and too much script time (approx 10 secs to load and initialize).
    • To wide for limited right column space
  • Technical development required to circumvent the above issues probably not available on d.o.
    • Use Ajax to dynamically load additional data as the user expands nodes. This is how MSDN's tree works.
      • But requires very fast server response
    • State of tree needs to persist across page loads
      • Or re-implement docs as an single-page JavaScript app that loads new page content by Ajax
In short, I don't think the full collapsible tree, or even the tree of one book, is likely to be implemented on d.o. as the navigation on every page.

Why that may be fine!

To satisfy most, if not all, of the "Understand the conceptual landscape" requirements it is not necessary to have the full tree on every page -- the user only needs for it to be available somewhere readily findable. In short, it can fulfill the requirements as a complement to the existing (or modestly revised) on-page navigation.
Implementing such a full TOC tree as a separate page has a number of benefits:
  • The development is relatively modest, as it's decoupled from existing book functionality, and is read-only on existing data.
  • It is a page that users would be highly motivated to load once, and keep in their browser for considerable time
    • Because they would avoid waiting to fetch the page again
    • They preserve current expand state of the tree.
    • So they would navigate from tree to pages by opening links in another tab or window
    • This would amortize the page size bandwidth over long times.
If implementation as a separate page makes full TOC feasible, then that has benefits:
  • Takes pressure away from the on-page navigation as the only way that users (and maintainers) get a view of overall conceptual and documentation structure.
    • Reduces frustration currently felt about that feature.
    • Reduces frustration with docs in general.

Critique of book module's structure model, nav and TOC

I'll be revisiting this shortly.