Experiment: Fresher looking Bazel docs

[Greg Estren]

Hi all,

I prototyped a Hugo / Docsy version of https://docs.bazel.build that I'd like to use to spark discussion on nudging the documentation quality forward.

You can see it at https://bazel-docsy.netlify.com/versions/ (page links don't really work but navbars do).

I think it highlights stylistic differences that have a qualitative effect on the documentation experience. Whether those could be implemented by a different rendering engine vs. tweaks to the existing engine are another question: what's most interesting to me isn't the technology but the UI principles demonstrated.

I also want to emphasize this is only exploring style. There's lots of work to do on content organization, good examples, tutorials, etc. I'm not trying to tackle that here.

Key improvements:

• Bigger font and shorter column lengths makes content feel less intimidating and wall-o-texty.
  
  
• Lovely right-side anchor menus for in-page navigation and orientation:
  
       
  
• Because of those menus, no need for in-page ToCs that take up valuable page real estate, scroll off the page, and are awkward to maintain. Example: before / after
  
  
• URLs don't show file extensions (i.e. https://bazel-docsy.netlify.com/versions/reference/build-style/ vs. https://docs.bazel.build/versions/2.0.0/skylark/build-style.html). This is both cleaner and less confusing when, e.g., editing links in .md files that get rendered to .html files in the URL.

As a holistic example, see

https://bazel-docsy.netlify.com/versions/extending/concepts/rules/

vs.

https://docs.bazel.build/versions/2.0.0/skylark/rules.html

The second looks a lot more dense and intimidating to me. A lot of that comes from the content itself and can't be eliminated by simple stylistic changes. But I think the first makes important stylistic choices that ease the user into the content and don't make the overall feeling so disorienting and encyclopedic.

Anyway, thoughts welcome!

[Aaron Gillies]

Hi Greg,

This looks really good to me.

I think even without given additional thought yet to content restructuring and the like, it achieves a lot in terms of increased readability.

Aaron

[Jon Brandvein]

I think even this simple prototype is already a net win. But I feel like we can make some further tweaks to the relative sizes of title fonts, normal text, and fixed width code blocks. The right nav bar is an improvement, as is not expanding every possible thing on the left by default.

[Tony Aiuto]

I like the direction. I want to push early for higher contrast ratios, (the right nav pane is unreadable), but there are many positives.

- the right nav pane vanishes if you make your window narrow. Huge win.  It means the important text is still there.

- the left nav pane shows you where you are in the doc hierarchy.

--
You received this message because you are subscribed to the Google Groups "bazel-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to bazel-dev+...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/bazel-dev/7b0fc20a-fc45-4887-9215-215db04356a0%40googlegroups.com.

[Jingwen Chen]

Thanks, Greg, for taking a stab at this! This looks much more comfortable on the eyes, so +1 to this being a net win. I'd love to see an example of this font/color/spacing theme on the current site.

To view this discussion on the web visit https://groups.google.com/d/msgid/bazel-dev/CACpMnuuB1gRBgzTC_ddebiuKEsuj5M%3Dxtt3cdbW9S4RO6GgBQg%40mail.gmail.com.

[László Csomor]

Ah, this is beautiful.

Easier on the eyes, and indeed feels just lighter.

--
László Csomor | Software Engineer | laszlo...@google.com

Google Germany GmbH | Erika-Mann-Str. 33 | 80636 München | Germany
Registergericht und -nummer: Hamburg, HRB 86891
Sitz der Gesellschaft: Hamburg

Geschäftsführer: Paul Manicle, Halimah DeLaine Prado

To view this discussion on the web visit https://groups.google.com/d/msgid/bazel-dev/CAMpM06Bfj-L1EhVbemS-1Jc68ZuLWeBYH0CbB5fhrgbm8Y7W5Q%40mail.gmail.com.

[Aaron Gillies]

Hi Greg,

Here are my notes from when I advocated for moving to Docsy.

Benefits:

• Improved accessibility
• Font too small
• Body text should be no more than ~80 characters per line
• Currently as many as ~140
• https://www.w3.org/WAI/WCAG21/quickref/?versions=2.0#qr-visual-audio-contrast-visual-presentation
  
• Better navigation support
• Supports nested navigation sections
• Supports breadcrumb navigation
• Can serve multi-version docs
• Meaning you can continue to have this functionality if you migrate
• Professional web design
• Docsy team contracted out to professional design firm for look and feel
• Notes about current site:
• Body size -- too small
• Heading size disproportionate to body font size
• Green highlighted text has low contrast ratio that is bad for readability
• Magenta code text is an unusual aesthetic choice -- not bad -- but more conventional highlighting styles might be better
• Some color theory could help out here
• Compare overall readability to GitHub rendered Markdown:
• GitHub rendering is black white + monochrome blue
• Bazel site looks like a triadic color scheme, which can appear busy to the eye
• Created and supported by Googlers
• Open Source
  
• Bazel team can continue to contribute

As far as URL patterns go, please do allow us to consult with you with respect to moving files around. We might be able to come up with a URL pattern scheme that makes it easier for the Bazel time to understand the performance of different categories of docs in Analytics by filtering on partial URL paths. (Then again, this might be a dream, but it would be great to explore this.)

Netlify supports global site redirects:

https://docs.netlify.com/routing/redirects/

But it's probably better to just bite the bullet and update links. I bet it's possible to do this programmatically and use link checkers to test. Note that this will require some care, as you will have to also update the various metadata that helps out on search findability on the g3doc side for the Blaze docs (Go links, User Added Results in Moma, g3doc redirects).

Way beyond this, I also suggested at the time to reduce the complexity of your single-sourced internal/external scheme by making the Bazel site the canonical reference for both Bazel and Blaze, and reducing the Blaze site internally to documentation that is specific to Google use cases. My guess is that this would be a pretty big thing to untangle and requires a sizing exercise before proceeding.

Aaron

[Aaron Gillies]

Also, if you have an accessibility advocate on the team, this person might find the following links useful:

• https://www.w3.org/WAI/standards-guidelines/wcag/
• https://g3doc.corp.google.com/company/teams/gar/web/web-basic-tests.md?cl=head -- also non-docs stuff in this link, but pretty good overall guidance

Aaron

[Tony Aiuto]

On Wed, Jan 29, 2020 at 10:19 AM Aaron Gillies <axgi...@google.com> wrote:

Also, if you have an accessibility advocate on the team, this person might find the following links useful:

• https://www.w3.org/WAI/standards-guidelines/wcag/
• https://g3doc.corp.google.com/company/teams/gar/web/web-basic-tests.md?cl=head -- also non-docs stuff in this link, but pretty good overall guidance

I am happy to advocate for accessibility. 

+1 we would welcome this. Especially interesting are the dimensions of static product material (vision, community, how to contribute) vs. the versioned (and often generated) docs.

 

Netlify supports global site redirects:

https://docs.netlify.com/routing/redirects/

But it's probably better to just bite the bullet and update links. I bet it's possible to do this programmatically and use link checkers to test. Note that this will require some care, as you will have to also update the various metadata that helps out on search findability on the g3doc side for the Blaze docs (Go links, User Added Results in Moma, g3doc redirects).

Way beyond this, I also suggested at the time to reduce the complexity of your single-sourced internal/external scheme by making the Bazel site the canonical reference for both Bazel and Blaze, and reducing the Blaze site internally to documentation that is specific to Google use cases. My guess is that this would be a pretty big thing to untangle and requires a sizing exercise before proceeding.

That might simplify a lot. Are there any successful examples of this you can point us to? A concern I have is when Blaze is substantially different from Bazel and we want Google users to know the difference.  Perhaps post-processing the Bazel site to merge in the Google differences, rather than trying to change entire sections.  Sort of like "Everything you read above is wrong: For google3 it is...."

[Aaron Gillies]

Hi Tony,

I'm not aware of another doc set that has the degree of complexity when it comes to the single-sourcing internal/external solution that Bazel has, plus the additional factor of managing in auto-generated reference docs.

However, we do publish the canonical Buganizer docs externally here for non-Googler users and a smaller subset internally here that represents the internal-only features.

The Blaze/Bazel case is different enough, though, that we'd really have to spend some time looking into the problem independent of precedents.

Aaron

[Greg Estren]

Thanks for all your feedback, everyone.

My next planned steps are to consult with Jin when he's back from traveling this week. He's been close to our documentation efforts and I want to at least be well-synced with him.

Then I'd like to lay out (small doc?) a clear multi-step process for moving forward and how to scope our priorities. I think a good model right now is taking off bite-sized chunks of the larger effort and giving them focus one-at-a-time. So I'd like to productionize my prototype without yet worrying about major organizational concerns, how to handle versioned/non-versioned/html/md/generated/sources, etc. But it's also important not to sabotage those future efforts when we're ready for them.

So in my view we should have some reasonable consensus on a big picture plan. Sequence it into chunks of work. Then take off one chunk at a time as we have the time to dedicate to it.

Most importantly: keep the documentation moving. We're not going to make it perfect tomorrow. But it should show credible progress and a general upward trend just like any other part of the Bazel project. We know our documentation needs work and we need to show we're paying attention to it.

Super-thanks to folks who are already demonstrating that  (e.g. many of the people on this thread).

[Laurent Le Brun]

Thanks for working on this, Greg!

I really like the direction it's taking.

Please keep us posted, and ask if you need help with anything.

To view this discussion on the web visit https://groups.google.com/d/msgid/bazel-dev/CABdTCQUE5og1HC_tbV-cyedtRU3769Yo%2BXjkYkgL2zbfQPeCSA%40mail.gmail.com.

--

Laurent

[Jingwen Chen]

Hi all,

Greg and I sat down today to work on refreshing the site design with the current documentation pipeline with Jekyll, to make it look as similar as possible with Greg's prototype with Docsy/Hugo.

Here is the result: https://bazel-docs-staging.netlify.com/versions/master/bazel-overview.html

New in this design:

* Sidebars are now sticky on scroll

* New right page-contextual sidebar with table of contents

* New "Create issue for this page" link in the right sidebar which opens up GitHub with pre-filled information

* General refresh of both code and non-code fonts, page density via font size and weight

* Removed big green bar at the top of the page

* Bolded active page title in the left sidebar

Please let us know what you think!

[Tony Aiuto]

Nice start.

On Tue, Feb 11, 2020 at 7:51 PM Jingwen Chen <jin...@google.com> wrote:

Hi all,

Greg and I sat down today to work on refreshing the site design with the current documentation pipeline with Jekyll, to make it look as similar as possible with Greg's prototype with Docsy/Hugo.

Here is the result: https://bazel-docs-staging.netlify.com/versions/master/bazel-overview.html

New in this design:

 

* Sidebars are now sticky on scroll

* New right page-contextual sidebar with table of contents

I don't like right sidebars at all. They get in the way of me shrinking the text to a thin vertical window and placing it alongside the window I am working in. I usually have to place the window so  the right sidebar is off screen.

* New "Create issue for this page" link in the right sidebar which opens up GitHub with pre-filled information.

Are we inviting a ton of doc bugs that we won't have time to fix?  :-)

 

* General refresh of both code and non-code fonts, page density via font size and weight

Generally very good. I would still make the text pure 100% black. No grey text unless needed.

 

* Removed big green bar at the top of the page

Yeah! 

* Bolded active page title in the left sidebar

That could be bolder. I only noticed it because you pointed it out.

[Aaron Gillies]

I think this is a great improvement already.

A couple of things that I would change:

- Retire the magenta font for monospaced typography. I would use black with a light gray background, for example. And then the minty green for linked text should probably be darker -- the W3C accessibility guidelines prefer a stronger contrast ratio for fonts:background on a page.

- Take a look at the body margins on the various responsive layouts. At the mobile-compatible layout, the left and right margins seem about right, but the mid-sized (tablet?) layout has considerably wider left and right margins. For the widest (desktop), I think it would be better for the main body to take up as much real estate as can be allotted, with the left and right navigation panels moving more flush against the margins.

- For the left-hand navigation, you can probably come down a few font sizes for the headings, and even reduce the font size used for the navigation entries. You might also reduce the leading (height between lines) to somewhat expand the amount of navigation that is visible at any given time, as well as allowing you to reduce the width of that panel.

- Consider using a light gray background to set apart navigation panels on the left and possibly right. Once a user is on a page that interests them, it's helpful to differentiate page elements functionally to signal to the eye something like, "Look here, this is the main body text," etc.

If https://docsy.dev is the model, note that the font sizing it uses can appear very large on some screens. I think it's worthwhile pulling the text size for all elements down a point or two and experimenting on a few devices to see what this looks like. One thing to think about is page length and overall information density on pages on the Bazel site. Right now, there isn't a lot of consistency, but you can really tax your users attention by having pages with a ton of scrolling required, as only a little bit of content is visible at any given time, making it more difficult to navigate through long text like the Bazel User Guide.

Aaron

[Jon Brandvein]

+1 to shrinking the font size just a tad. It'd also be good to let the content breathe a little more in the middle and push the sidebars out in either direction a bit, maybe with slightly more characters per line.

The font size difference between inline code text and normal body text is still a little jarring. I can see the advantage to having inline code take up less space in a line, but I think it hurts readability of paragraphs.

You received this message because you are subscribed to a topic in the Google Groups "bazel-dev" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/bazel-dev/hjRP7JTtZ_U/unsubscribe.
To unsubscribe from this group and all its topics, send an email to bazel-dev+...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/bazel-dev/CAKPwNspu9He9VzP_R%2BNDdVOi_1awn-v%2B7mqbodZHgMWhmhNsuA%40mail.gmail.com.

[Tony Aiuto]

But please all sizes and distances must be specified in POINTS and not pixels. The delta between my laptop and desktop resolutions is so large that no single pixel size can possibly be correct.

[Greg Estren]

* New right page-contextual sidebar with table of contents

I don't like right sidebars at all. They get in the way of me shrinking the text to a thin vertical window and placing it alongside the window I am working in. I usually have to place the window so  the right sidebar is off screen.

Note that these automatically disappear when the window is made narrow enough.

 

* New "Create issue for this page" link in the right sidebar which opens up GitHub with pre-filled information.

Are we inviting a ton of doc bugs that we won't have time to fix?  :-)

 

We should bias ourselves toward this problem vs. the opposite problem. We can always remove the link if that problem became real. But part of a good documentation experience I think needs to be clear and regular communication between users and devs.

[Rob Sayre]

On Wed, Feb 12, 2020 at 10:40 AM 'Tony Aiuto' via bazel-dev <baze...@googlegroups.com> wrote:

But please all sizes and distances must be specified in POINTS and not pixels. The delta between my laptop and desktop resolutions is so large that no single pixel size can possibly be correct.

This should be ok in "px". These are different from "device pixels". All the gory details: https://webplatform.github.io/docs/tutorials/understanding-css-units/

In the end, the docs will probably need a few media queries for vertical displays, though.

thanks,

Rob

 

[Tony Aiuto]

What is a "media query"?

But the meta question behind that is really, "what techniques do you use to make sure pages are good on a wide variety of displays?"

[Aaron Gillies]

Media queries are part of the HTML4 W3C standard:

https://www.w3.org/TR/css3-mediaqueries/

These are implemented on the browser side and are used to make decisions about how to render pages conditionally based on available screen dimensions and other factors.

I wrote the original Bazel site CSS, which at that time rendered a site that was not responsive to different screen dimensions. Another Bazel contributor updated it to use the Bootstrap framework, which made it easier to view on Mobile and other non-desktop/laptop screens. At that time, I verified how it looked using one of several available emulators like this one:

http://www.isresponsive.com/ViewOnDevice?site=http://bazel.build

Aaron

[Jingwen Chen]

Yep, we are already using media queries. In fact, the left and right sidebars already respond to @media queries, which are hardcoded to 992px as the width threshold.

[Greg Estren]

I also suggest we do some light organizational cleanup of the left-side navbar as part of this milestone.

There's some serious low-hanging fruit that takes little time to clean up. I see no reason not to tweak it now.

I tried a clean up that I'm attaching to this message. Preview directly at https://htmlpreview.github.io/?https://github.com/gregestren/bazel-website-previews/blob/master/Bazel%20Overview%20-%20Bazel%202.1.0.html.

What this attempts to do:

• Make titles more concise. Remove redundancies (i.e. "Remote Execution" -> "Guidelines for Remote Execution")
• Separate sections for  installing vs. using Bazel
• Try to organize the sub-sections a bit more coherently, and with easier to parse concepts.
• Move  obviously reference-y stuff to the reference section (in the current site click on the first entry under "Installing and Using Bazel -> BUILD files" and you get something very reference-y and very intimidating for someone just trying to understand what a BUILD file is).
• Standardize titles a bit more (ie.. "Best Practices" for both "Using Bazel" and "Extending Bazel")

I'd also like to standardize the spelling but I don't know what best practice is. "All Caps" or "Just first word"?

I'll put up a PR for this for deeper review. I get this is hard to get 100% right now and some of the choices I made may not stick. Getting to the next level of coherency will required deeper design effort beyond what I'm trying to do.

[Greg Estren]

On Wed, Feb 12, 2020 at 6:34 PM Greg Estren <gre...@google.com> wrote:

 

I'll put up a PR for this for deeper review. I get this is hard to get 100% right now and some of the choices I made may not stick. Getting to the next level of coherency will required deeper design effort beyond what I'm trying to do.

https://github.com/bazelbuild/bazel/pull/10775

[Tony Aiuto]

Thanks for educating me.

[Jingwen Chen]

Thanks all for the feedback! Pushed an update: https://bazel-docs-staging.netlify.com/versions/master/bazel-overview.html

- Made left sidebar and headers smaller, to give the content more breathing room.

- Retired magenta code color to black with light grey background.

- Shrinked header font sizes throughout a little bit.

- Darkened links.

[Jon Brandvein]

Oooh, pretty.

Is there a way to better distinguish right navbar items from each other, in particular when an item is wrapped on multiple lines? On this page they almost look like one big wrapped paragraph.

I'm missing having a splash of color in the code text, but I could get used to it.

[Jingwen Chen]

On Tue, Feb 18, 2020 at 11:51 AM Jon Brandvein <bran...@google.com> wrote:

Oooh, pretty.

Is there a way to better distinguish right navbar items from each other, in particular when an item is wrapped on multiple lines? On this page they almost look like one big wrapped paragraph.

Sure, just pushed a change: https://bazel-docs-staging.netlify.com/versions/master/user-manual.html

[Greg Estren]

On Tue, Feb 18, 2020 at 12:19 PM Jingwen Chen <jin...@google.com> wrote:

On Tue, Feb 18, 2020 at 11:51 AM Jon Brandvein <bran...@google.com> wrote:

Oooh, pretty.

Is there a way to better distinguish right navbar items from each other, in particular when an item is wrapped on multiple lines? On this page they almost look like one big wrapped paragraph.

Another low-tech solution I think we should strive for is shortening the text. 

[Jon Brandvein]

Indeed. Sent a fix your way for that page, but we should do that more broadly.

[Jingwen Chen]

Update: we're planning to deploy the new Bazel site design tomorrow (2020-02-20) at around 4PM ET.

You can preview the latest design here: https://bazel-docs-staging.netlify.com/

[Greg Estren]

Also see https://github.com/bazelbuild/bazel/milestone/19 for miscellaneous light content refreshes that will accompany this (they'll take a bit more time to show up because the content is versioned).

[Andrew Allen]

Is there any documentation on the way the new hugo docs are built? The word "hugo" doesn't seem to appear in the bazelbuild/bazel repo, Is there a separate docs repo that I'm missing?

/** ~Andrew Z Allen */

--

You received this message because you are subscribed to the Google Groups "bazel-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to bazel-dev+...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/bazel-dev/CAMpM06Dv-_9YfpJLcwWKtaWOYivAy0NQZr7Npu9vyPwTEACoMg%40mail.gmail.com.

[Jingwen Chen]

There's no Hugo involved in this yet. It's a re-skinning of the current site.