Documentation navigation

[ChrisDodic]

These opinions come from my experience learning the Ocean SDK from the documentation directly and some code examples.

Sidebar: I feel that there should be more distinction in the sidebar which links are part of the ocean documentation, and which is part of the more general dwave system documentation. The "D-Wave" section (containing links for D-Wave, Leap, and D-Wave System Documentation) seems to be part of the ocean documentation. Maybe it should be forced to the bottom of the navbar or each entry should be indented to show that it is part of another section.

Tools: I did not immediately correlate this section as the location for the documentation (even though it is clearly labelled at the Ocean docs starting page), and I think this was because I was immediately gravitated towards the "Getting Started" section which does not feature a link to the individual tools documentation. Perhaps this can be mitigated by linking the "Tools" main page in the "Getting Started" page. After viewing this page again, I now realize it is accessible via the "Ocean Software Stack" section, but might be worth having its own description section.

Edit: I have just noticed that the "sub-pages" (tool specific documentation) has a more clear distinction in the navbar. Seems this may just be due to inconsistent style. Example: Compared with:

[JoelPasvolsky]

@ChrisDodic, thank you for your feedback. We hope to soon take some big steps in integrating Ocean docs from the various repos which will improve navigation through the sidebar--see https://github.com/dwavesystems/docs/pull/62.

Regarding "Maybe it should be forced to the bottom of the navbar" --> is this not already the case somewhere? In both your example screenshots above, the non-Ocean links are at the bottom, under a "D-Wave" header. For ""Getting Started" section which does not feature a link to the individual tools", when on any page there, you can access tools docs through the sidebar's Tools link. I think that post-https://github.com/dwavesystems/docs/pull/62 the sidebar will take more focus from being more helpful and users will tend to navigate through that rather than additional links on the pages.

[ChrisDodic]

I need to work on my clarity! In regards to:

Maybe it should be forced to the bottom of the navbar

I should have re-addressed this in my edit, but it seems that the sections ('current section', "Ocean Software", "D-Wave") are more clearly distinct on the specific tool pages, but for the main Ocean Docs page (https://docs.ocean.dwavesys.com/en/latest/) they seem to 'blend' together since the "D-Wave" section header is in grey as well as the link text (albeit different shades).

Current:

Proposed:

It seems that this is due to slightly different style sheets being used between the two.

Snippet from the dwave binary csp theme.css (https://docs.ocean.dwavesys.com/projects/binarycsp/en/latest/index.html#):

.wy-menu-vertical p.caption {
 color:#3a7ca8;
 height:32px;
 display:inline-block;
 line-height:32px;
 padding:0 1.618em;
 margin:12px 0 0 0;
 display:block;
 font-weight:bold;
 text-transform:uppercase;
 font-size:85%;
 white-space:nowrap
}

Snippet from dwave ocean home theme.css (https://docs.ocean.dwavesys.com/en/latest/):

.wy-menu-vertical p.caption {
 height:32px;
 display:inline-block;
 line-height:32px;
 padding:0 1.618em;
 margin-bottom:0;
 display:block;
 font-weight:bold;
 text-transform:uppercase;
 font-size:80%;
 white-space:nowrap
}

Hopefully this helps. Thanks for the reply!

Also, I was not aware of #62 , it seems like that would address my concerns about accessing the specific tools. Thanks again for sharing that.

[JoelPasvolsky]

Thanks for clarifying @ChrisDodic!