Proto and gRPC introductory documentation

[aaliddell]

A WiP document guiding users on the use of Protobuf and gRPC with Bazel, following from https://github.com/bazel-contrib/SIG-rules-authors/discussions/26 and other discussions on mailing list.

You can see a live version of the page here for review: https://aaliddell.github.io/SIG-rules-authors/proto-grpc

This is still a draft, as there are a few outstanding points:

• Table is not embedding correctly
• Is American English preferred? e.g colour vs color, summarises vs summarizes etc
• The recommendations need reviewing
• The GH pages site needs index, theming (and icon?) etc
• What have I missed? It's easy for me to assume users know things, when they're not obvious to those unfamiliar with the topic
• I need to run through for final proof read, as there's probably a dangling sentence somewhere in there.

[alexeagle]

high level questions - yeah I agree the GH template needs some work, it's too narrow - let's leave that presentation bit until after we have the markdown content.

IMO there's no one to dictate a style guide and I appreciate the voice of the author so whatever dialect you prefer. I suppose a good tech writer would modify some words here and there for wider readability. Maybe the SIG can attract one of them someday.

[aaliddell]

IMO there's no one to dictate a style guide and I appreciate the voice of the author so whatever dialect you prefer. I suppose a good tech writer would modify some words here and there for wider readability. Maybe the SIG can attract one of them someday.

I dont mind either way, so I've switched the obvious cases to US English, since that's generally the biggest userbase.

[pcj]

I reviewed the document. I could imagine more content in the areas of:

• Relationship of FileDescriptorSet with proto_library and descriptor_set_in.
• Relevant bazel flags and explanations.
• Toolchains, how to use a prebuilt protoc.
• More language-specific stuff, etc.

However, those things could be added later, I don't think adding new documentation scope is necessary to merge this.

Thanks @aaliddell for working on this!

[alexeagle]

For the theme, how about remote_theme: pmarsceill/just-the-docs

https://alexeagle.github.io/SIG-rules-authors/proto-grpc.html

seems popular from some searching, and it's wider than the current one

[aaliddell]

For the theme, how about remote_theme: pmarsceill/just-the-docs

https://alexeagle.github.io/SIG-rules-authors/proto-grpc.html

seems popular from some searching, and it's wider than the current one

Look OK to me

[aaliddell]

To tie up all the things left open:

• A gazelle -> proto_library section would be useful following from the discussion above, but I don't think I'm well placed to write it, as I generally don't have enough experience with Gazelle. So yeah, I'll leave that open to anyone that feels they know it well.
• "Toolchains, how to use a prebuilt protoc." This is semi covered in the issues section discussing caching
• "Relevant bazel flags and explanations." There only seem to be a few documented proto relevant flags remaining nowadays, of which the only one I've still seen used is the experimental --experimental_proto_descriptor_sets_include_source_info when using documentation plugins.
• You probably want to fixup the index page for the GH pages site. Something like what the SIG is, who's sponsoring it, what it's funding etc.
• "Relationship of FileDescriptorSet with proto_library and descriptor_set_in." This'd probably fit in a section on 'Implementing a Ruleset', which is a book all of its own.

[alexeagle]

Yup I can fix the index page, or someone else can take the content from the current readme and just move it to GH-pages branch

[alexeagle]

Hey @aaliddell do you think we can merge this as-is, and you can invoice your hours to the SIG open collective?

[aaliddell]

Fine by me