>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #1289090. --> Reported by: [jhodgdon](https://www.drupal.org/user/155601) >>> <p>This is part of <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/documentation/-/work_items/1278256" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/documentation/-/work_items/1278256</a></span>. Original statement: "In the process of making docs clearer they are community-maintained, we decided we should have some kind of new navigation (maybe)."</p> <h2>Contents of this issue</h2> <ul> <li><a href="https://www.drupal.org#toc0">Overview</a></li> <li><a href="https://www.drupal.org#toc1">Requirements</a> and <a href="https://www.drupal.org#toc2">constraints</a></li> <li><a href="https://www.drupal.org#toc4">Candidate alternatives and examples</a></li> <li><a href="https://www.drupal.org#resolution">Proposed resolution</a></li> </ul> <h2 id="toc0">Overview</h2> <p>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:</p> <ul> <li><b>Doc page nav: </b>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.</li> <li><b>Search: </b>d.o's search, and google/bing etc</li> <li><b>Tags, </b>tag search</li> <li><b>Doc map: </b>Stand-alone page with complete table-of-contents tree (not currently implemented)</li> </ul> <h2 id="toc1">Requirements</h2> <p>The overall set of "navigation" features should support the following activities, and make them faster, easier, and/or more possible than they are now:</p> <ul> <li><strong>Find documentation again that you have seen before</strong></li> <li><strong>"Find documentation on a topic":</strong> This could be supported through search (both on-site, and google etc) and navigating through the book outlines.</li> <li><strong>Find a place to put information</strong>: 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.</li> <li><strong>"Understand and explore the conceptual and documentation landscape":</strong>. (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. <ul> <li>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.</li> </ul> </li> <li><strong>For each doc page: "Where am I?", "Go nearby" and "continue reading"</strong>: 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: <ul> <li>Show location within hierarchy (links to ancestors)</li> <li>Links to subsidiary pages that explain more details.</li> <li>Links to broader pages that put the current page into context.</li> <li>Links to preceding pages that introduce topics used on the current page</li> <li>Links to succeeding pages that follow on from the current page</li> </ul> </li> <li><strong>"Find related pages, elsewhere in the hierarchy" .</strong> Suggest pages covering related topics <ul> <li>Could be implemented via specific links in the content (as now)</li> <li>Could use keyword tags [which we have, but pages are not widely tagged with keywords]</li> </ul> </li> </ul> <h3 id="toc2">Constraints</h3> <ul> <li>Visual design: Amount of space used on page</li> <li>Usability: <ul> <li>Obviousness without explanation</li> <li>How much clicking and scrolling required</li> </ul> </li> <li>Accessibility: people with vision/mobility limitations must also be able to use the navigation</li> <li>Performance <ul> <li>Bandwidth required</li> <li>Computation required in client browser</li> </ul> </li> <li>Implementation difficulty level (and likelihood)</li> </ul> <h2 id="toc4">Candidate alternatives and examples</h2> <p>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:</p> <ul> <li>Choice of how many pages are shown, and which ones.</li> <li>Interactivity (expand/collapse)</li> <li>Browsability (Does widget show all pages?)</li> <li>Scalability (Even if a mock-up is attractive, can it handle a collection the size of d.o docs?)</li> <li>Use of space on the page</li> <li>Performance</li> <li>Implementation effort required</li> </ul> <h3>Table of alternatives and their characteristics</h3> <p> <img border="0" src="http://drupal.org/files/gw-proposals-spreadsheet01.PNG" width="460" height="337"></p> <h3 id="toc5">Current drupal.org docs navigation</h3> <p><img border="0" src="http://drupal.org/files/gw-prop-01-existing.PNG" width="470" height="284"></p> <h3 id="toc6">Plone-style menu</h3> <p>References:<br> <a href="http://drupal.org/node/1278256#comment-4991304">#19</a>, <a href="http://drupal.org/node/1278256#comment-5040744">#75</a>, <a href="http://drupal.org/node/1278256#comment-5040998">#77</a>, <a href="http://drupal.org/node/1278256#comment-5061320">#93</a>, <a href="http://drupal.org/node/1278256#comment-5069134">#100</a></p> <p>Displays a dropdown list of page titles, using dotted numbers (like 3.5.2) to indicate hierarchy.&nbsp; Displays the <i>entire</i> 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).</p> <p> <img border="0" src="http://drupal.org/files/gw-prop-02-plone.PNG" width="591" height="254"></p> <h3 id="toc7">Mega dropdown</h3> <ul> <li>References: <a href="http://drupal.org/node/1278256#comment-5070162">#112</a></li> <li><a href="http://www.useit.com/alertbox/mega-dropdown-menus.html">Jakon Nielsen: Mega Drop-Down Navigation Menus Work Well</a></li> <li><a href="http://econsultancy.com/us/blog/3543-huge-drop-down-menus-good-for-usability-nielsen">3543-huge-drop-down-menus-good-for-usability-nielsen</a></li> <li><a href="http://www.useit.com/alertbox/mega-menus-wrong.html">http://www.useit.com/alertbox/mega-menus-wrong.html</a></li> <li>Main innovation is to display "large number" (say, a few dozen) of items using multiple columns, or at least spread out in 2D on the menu surface.</li> <li>Not clear how this applies to displaying doc page navigation</li> </ul> <p> <img border="0" src="http://drupal.org/files/gw-prop-03-megamenu.PNG" width="440" height="273"></p> <h3 id="toc8">"Tidy collapsed menu"</h3> <p>References: <a href="http://drupal.org/node/1278256#comment-5000836">#32</a>, <a href="http://drupal.org/node/1278256#comment-5064212"> #96</a>, <a href="http://drupal.org/node/1278256#comment-5071796">#120:</a><br><br> Live example at open atrium docs: <a href="https://community.openatrium.com/documentation-en/">https://community.openatrium.com/documentation-en/</a><br><br> 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<br> existing context on each click.</p> <p><img border="0" src="http://drupal.org/files/gw-prop-04b-tidymenu-oa.PNG" width="506" height="236"></p> <h3 id="toc9">Scrolling list box</h3> <p>Reference: <a href="http://drupal.org/node/1278256#comment-5070302">#114</a></p> <p>"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.</p> <h3 id="toc10">MSDN-style menu</h3> <p>MSDN gives three different options for navigation, which can be selected via the "options" (gear icon) menu.</p> <ul> <li>Classic: </li> <li>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.</li> <li>ScriptFree: Displays a column divided vertically into three areas: <ul> <li>List of ancestors</li> <li>List of children</li> <li>List of peers</li> </ul> </li> </ul> <p><b>Classic</b> </p><p>Expandable tree able to show the entire hierarchy of MSDN docs. Clicked branches retrieve data for children via Ajax.</p> <p> <img border="0" src="http://drupal.org/files/gw-prop-06c-msdn-classic.PNG" width="450" height="289"></p> <p><b>Lightweight:</b> </p> <p>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.</p> <p> <img border="0" src="http://drupal.org/files/gw-prop-06b-msdn-lightweight.PNG" width="435" height="247"></p> <p><b>ScriptFree:</b> </p> <p>Displays a column divided vertically into three areas:</p> <ul> <li>List of ancestors</li> <li>List of children</li> <li>List of peers</li> </ul> <p> <img border="0" src="http://drupal.org/files/gw-prop-06a-msdn-scriptfree.PNG" width="410" height="305"></p> <p><a href="http://drupal.org/node/1278256#comment-5070930">#117</a> 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.</p> <p> <img border="0" src="http://drupal.org/files/gw-prop-07-juliakm-msdn-style.PNG" width="569" height="323"></p> <h3 id="toc11">Stand-alone Documentation Map page</h3> <p>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 <strong>"Understand and explore the conceptual and documentation landscape".</strong> </p><p>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.</p> <p>Prototypes, using actual d.o data:<a href="http://grahamwideman.wikispaces.com/Drupal+docs+by+book">http://grahamwideman.wikispaces.com/Drupal+docs+by+book</a></p> <p><img border="0" src="http://drupal.org/files/gw-prop-10-gw-tree-all-books.PNG" width="547" height="416"></p> <h3 id="toc12">No navigation</h3> <p><a href="http://drupal.org/node/1278256#comment-5071796">#120</a> 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<br> effort.</p> <h2 id="resolution">Proposed Resolution</h2> <p>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:<br> <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-6"><a href="https://www.drupal.org/project/documentation/issues/1508832" title="Status: Closed (works as designed)">#1508832: Support +/- expand/contract in Book navigation on Drupal.org</a></span></p> <p>Still to be resolved: Can we also do something to help with:</p> <ul> <li>search</li> <li>find related information in other places</li> <li>understand the overall picture</li> </ul>