Created by: gwideman, Mar 12, 2012 1:36 am
Revised by: gwideman, Mar 26, 2012 12:26 pm (15 revisions)

Introduction

On a couple of pages subsidiary to this one, I provide a treeview presentation of the drupal.org documentation hierarchy, As a preview, this image shows the general idea:
drupal-tree-screencap01.PNG
The current page provides a few notes on how to read and use these trees.

Different views

At current writing (2012-03-12) I have provided two different views of the data.

Documentation organized by book

View here.
All but about 40 of the ~8100 pages are (Drupal) book pages. This presentation portrays a tree where all the top-level book pages are direct children of the top tree node. This provides the best-organized way to explore book-by-book.

Documentation tree from /documentation

View here.
On drupal.org, the segregation of content by book is not prominently displayed (unless you know to look at the TOC title). Instead, the user proceeds from the /documentation page and then digs down.. and around...etc.
So the main intent of this tree is to use /documentation as the top-level node, and shows the hierarchy from there down.
There is a snag to this, however. Starting from /documentation, the hierarchy enters some books through their top page, but enters others through one (or more) of their subordinate pages. Since I build these trees without following any of the explicit "up" links, this leaves out parts of some books.
As an accommodation, I also include a second top-level node ("orphans") which contains all the top-pages of books which the /documentation tree did not reach. This is intended to create a complete coverage of all the content, but covers parts of some books twice, so the end result is a total number of nodes that is more then the total number of pages.

Navigation and browsing

Navigating the tree

  • To open a branch of the tree,click on the icon next to an item.
    • Avoid clicking the text, as those are usually links
  • A few nodes have [++] or [--] symbols. You can use those to expand or collapse all subsidiary nodes at once.
    • Yes, this feature needs to be on more nodes and have a better UI. Working on that.
  • Search: You can use the browser's search function. This only finds visible nodes, so it's useful to open all nodes first.

Following a link

The title in most nodes in the tree are clickable links to the corresponding page on drupal.org. I suggest:
  • Do not click directly on the links, because when you return to the tree page you will have to endure a wait while the browser recomposes the page. Instead:
  • Better: Right-click > open in new tab or window.
  • Best: Arrange two browser windows so you can drag a link from the tree to the second window. Either drop into an open tab, or drop it as a new tab. This is a very fast way to browse and survey pages.

Key to symbols and data

Color scheme

The color scheme (combination of background and foreground colors) indicates which book the node pertains to.
drupal-tree-colorschemes01.PNG
  • gw00pg_l.pngThe black-on-grey icons are reserved for "non-book" pages.

The icons

The shape of the icon indicates what kind of a node this is, and whether it's expanded or collapsed.
Icon
Description
gw08bk_s.png
Top-level page of a book, closed. Click to open.
gw08bk_o.png
Top-level page of a book, open. Click to close
gw08pg_s.png
Subsidiary page (within a book), with child pages. Closed. Click to open.
gw08pg_o.png
Subsidiary page (within a book), with child pages. Open. Click to close.
gw08pg_l.png
Subsidiary page within a book, with no child pages. No point in clicking :-).
gw20bk_s.png
Link to top-level page in a different book (hence different color). Closed. Click to open, etc. This appears in trees which follow hierarchy across books.
gw20bk_sa.png
Link to top-level page in a different book.This icon appears in trees which don't provide the "other book's" child pages. Hence this icon isn't clickable.
gw20pg_sa.png
Link to top-level page in a different book. Again, the page may have child pages, but they are not included in this tree,and the icon is not clickable.

The attached data

At current writing (2012-03-12) the following data may be attached to each node. The data is not displayed if it's unavailable, or zero.
Brackets
Sample data
About
First item
Second
Third
( )
(17/34)
Subsidiary
pages
Count of direct children
Count of all descendants

[ ]
[4.9k, 2010-07-15, a:4]
Page data
Size of text in the body of the article, excluding the "Last updated" and child navigation sections. (div.node-content, less p.updated and div.book-navigation).
Date of last update
Count of authors
{ }
{10/5, 2011-08-08}
Comments
Number of comments
Number of comments since last update [Note 1]
Date of last comment

Notes

  • [1]: Actually, because no time-of-day is mentioned in the "Last updated" field of a page, we can't tell if a comment on that same day is before or after. Currently I count it as after. In any case, in the tree you can glance at the "Date of last update" and "Date of last comment" for a hint as to whether there are likely to be comments of interest.
  • Intrusiveness: In this initial version of the tree, I think the data is too visually intrusive. It would be better displayed in columns in a tree-grid. I am exploring performance of different tree-grid implementations.

Which links and pages are include where?

I need separate documentation on algorithms used, but for now, brief notes:
  • In general, the algorithms use links only from the content part of the page, usually only from the explicit list of child pages at the bottom of the content area.
    • And specifically not the TOC table in the right column.
  • For some books, their main pages lack a table of child pages, so for main pages I used all the links in the content area.
    • Likewise on the /documentation page.
The two trees differ in the exact details of whether they follow the hierarchy across books. That is to say, if a page in Book A has a link to Book B, then does the entire hierarchy of Book B appear at that location in the tree, or just a single link to that "foreign" page?
  • This is mostly an issue on book main pages, since for other pages the algorithm is only looking at the direct child list of links, which by definition are in the same book.

To-do list 2012-03-26

  • On top-level book pages, remove the listing of links from the content area. Show only child pages.
    • Possibly add a "content-area links" item, under which to place content-are links.
    • Experiment with putting the content-area links under h2/h3/etc headings
  • Tone down the icons for "pointer to other book" -- too visually distracting
    • ...though that may be less of an issue if they are hidden under "Content-area links"
  • Remove "link to page in other book" text
  • Implement some form of tree-table, with the node data moved to columns (to the right)