[GitHub] incubator-brooklyn pull request: Improve document usability - navi...

[aledsage <gi...@git.apache.org>]

Github user aledsage commented on the pull request:

    https://github.com/apache/incubator-brooklyn/pull/519#issuecomment-76716501
  
    Looking at the two options again, I see pros and cons for each (I've called the options "full menu" and "current context only").
    
    I wonder if we need to put this on hold until folk have more time to focus on it (or if there are any quick wins that move us towards the best of both options).
    We need to be sure to invest our time in what is agreed to be the right future direction.
    
    A big concern with the "full menu" option is that the menu takes up a lot of vertical space once you've navigated to the appropriate page - e.g. expand "User Guide -> YAML Blueprints -> Chef in YAML Blueprints -> About Chef". There are about 30 things shown in the menu.
    We don't want to have to scroll to see the menu options.
    We don't want it to get harder to use over time as more pages are added.
    It's nice to have the menu float (i.e. always visible at the top of page) - that is only possible if scrolling will never be needed, even on low resolution displays. Alternatively we could have separately scrollable sections on the page, but that is out of vogue.
    A couple of minor improvements to @bostko's menu would be: why are the lines being wrapped; why is there so much white space between rows.
    
    For the current "current context only" option. I worry it will confuse users when the menu changes - 
    it's not clear enough that the breadcrumbs at the top are showing the hierarchy that these items are under.
    It's also slightly harder to navigate back if the user goes to the wrong page (because their model of the menu has been entirely changed, with the previous links having disappeared).
    
    For the "current context only" option, perhaps an improvement would be to show the sibling pages indented so it's clear they are child pages of the top-level hierarchy.
    There could perhaps be a "..." to show that uncles etc have been hidden.
    
    Another interesting feature of the "current context only" option is that pages can appear in more than one place. For example, "developer guide" also appears under "user guide -> other 0.7.0-M2-incubating resources".
    This makes sense for a context-based menu - it's showing the pages that are relevant for where you've navigated to. But it would not make sense when showing someone a full hierarchy.
    I'm on the fence as to how useful that is, versus improving our cross-references and our searchability.
    
    I think there are entirely orthogonal issues around searchability and improving the structure so things are more logically grouped in the right places.
    Let's not let those considerations affect this particular discussion.



---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---