New Bazel Documentation

[Lyra Levin]

Lyra Levin <phil...@google.com>	10:20 AM (1 hour ago)
to bazel-discuss

The Bazel team is excited to announce migration to a new docs experience! Check it out and tell us what you think. Go ahead; we’ll be here when you get back.

Renewing the Bazel documentation infrastructure was a team priority in 2021. Along with improving findability, the new site also makes it easier to scale and contribute so we can continue to grow our knowledge base together.

The new documentation has several new features:

• Better user experience. With automated localization / translation, filterable sitemaps, and a consistent navigation structure, more users can find what they are looking for, faster.

• Standardized contributor experience. We’re making regular improvements to our documentation, and encourage the community to contribute.

• Improved information architecture. The refactored sitemap and landing pages give a professional feel to the site, and improve consistency with other Google OSS project sites like Tensorflow, Android, and Firebase OSS.

• Less engineering burden. Reduced site infrastructure maintenance toil frees time for other Bazel ecosystem initiatives. 

Welcome to the new bazel.build. Like what you see? Find a bug? Let us know. We want the new docs site to be a place you want to build in.

Many thanks to the writers, engineers, and site specialists who made this migration possible — including you, the Bazel community. See you in the docs!

- The Bazel Docs team

--

Lyra Levin | Writer | phil...@google.com | 415.579.8580

[Julian Amann]

Here is my rant ;): 

1. For me hermetic builds are missing as an argument on the landing page -> "Why bazel". In the past we had "fast and correct"- correct was dropped?

2. The "new" Bazel logo reminds me more about the top right top figure of the Tensorflow landing page - I do not understand why we have routes and nodes in the Bazel logo - is this the dependency graph? - I do not get the idea here 

3. It is important for me to be able to switch between the documentation of different Bazel versions - in the old documentation you could select the version under consideration via a combo box located at the left top - I could choose between "main", "4.0.0", "5.0.0", "2.0.0" etc. - How can I do this with the new documentation? This feature seems to be missing or well hidden

4. In the old documentation it was easy to fix a spelling mistake or some minor errors - every documentation page had a direct link to the corresponding GitHub page to perform the edit - this is missing now - now I have to checkout Bazel and find the corresponding .md file myself 

What I like:

It is now better structured

Best regards,

Julian

[Florian Weikert]

Hey Julian,

Thank you very much for the feedback!

Some thoughts:

Re 3.: We're still working on versioned documentation. For now we'll keep docs for Bazel <= 5.0 on docs.bazel.build, and all releases >= 5.1 will be on the new homepage. However, we definitely need to add more links to make navigation between different versions easier.

Re 4.: Yes, we should bring this feature back, especially since the location of the docs has changed (https://bazel.build/foo/bar = /site/en/foo/bar.md on GitHub).

Florian Weikert

Senior Software Engineer

f...@google.com

Google Germany GmbH

Erika-Mann-Str. 33

80636 München

Geschäftsführer: Paul Manicle, Liana Sebastian  

Registergericht und -nummer: Hamburg, HRB 86891

Sitz der Gesellschaft: Hamburg

Diese E-Mail ist vertraulich. Wenn Sie nicht der richtige Adressat sind, leiten Sie diese bitte nicht weiter, informieren Sie den Absender und löschen Sie die E-Mail und alle Anhänge. Vielen Dank.

      

This e-mail is confidential. If you are not the right addressee please do not forward it, please inform the sender, and please erase this e-mail including any attachments. Thanks.

--
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/c170be82-8710-4b3c-a536-d06d2e0cf636n%40googlegroups.com.