Community Contributed Tutorials Destination and Linking with Bazel.build

[Radhika Advani]

Hi Everyone,

In the last rules author SIG on the 20th Sep 2022 - we spoke about tutorials being contributed by the community for Bazel. We wanted to understand if it's possible to create documents on Github and then have them linked from Bazel. build. The idea is to reduce documentation fragmentation - by having all documents listed on individual sites 

would love to hear everyone's thoughts so we can align and close on this topic

Regards,

Radhika

[Alex Eagle]

Benefits I see from having tutorials in each rule repo:

- can atomically change a rule and update the tutorial

- search-and-replace in the rules will find tutorial references

- naturally versioned by tags in that repo

- subject matter experts for the tutorial are already CODEOWNERS

Benefits on a central place like https://bazel-contrib.github.io/SIG-rules-authors/:

- rules authors don't have to figure out how to host GH pages or agree to increased maintenance scope of accepting PRs to tutorial content

- topics that naturally span across rulesets have a logical place to go (e.g. using Docker with Python)

- one place to hook up search and versioning

- can atomically change a bunch of tutorials

- can have shared supporting infra like templating engine for content, search index and UI, etc

- consistent nav experience for users

https://bazel-contrib.github.io/SIG-rules-authors/proto-grpc.html was meant to be the first in a series, but we didn't get volunteers to write anything so far.

-Alex

--
You received this message because you are subscribed to the Google Groups "bazel-contrib" group.
To unsubscribe from this group and stop receiving emails from it, send an email to bazel-contri...@googlegroups.com.
To view this discussion on the web, visit https://groups.google.com/d/msgid/bazel-contrib/b91f86f9-aa3c-4979-acdd-c4928d64eae3n%40googlegroups.com.

[Brentley Jones]

When this was discussed in the past, in particular around the very outdated iOS tutorial that exists on the Bazel website, we decided that having it hosted on the rules_apple repo was best because of the reasons you listed Alex. And even though it might span a couple rulesets (rules_apple, rules_swift, and rules_xcodeproj), being able to have it versioned by that repo and naturally updated as we update the rules, was a huge motivator.

[Tony Aiuto]

One more consideration.

• Generic Bazel docs will eventually need examples that track LTS versions. We want to highlight how to do things with the current Bazel, but still provide entry ramps for new users to older releases.
• Rule sets will have the same need, but it might be driven by the rules release rather than the LTS track.

To view this discussion on the web, visit https://groups.google.com/d/msgid/bazel-contrib/88f137e9-9d01-4507-8e41-e8a814d9d14dn%40googlegroups.com.