brooklyn-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From aledsage <>
Subject [GitHub] incubator-brooklyn pull request: Improve document usability - navi...
Date Mon, 02 Mar 2015 14:05:25 GMT
Github user aledsage commented on the pull request:
    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
    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 or file a JIRA ticket
with INFRA.

View raw message