#development
Title
h
hundreds-father-404
04/15/2022, 3:39 PM@narrow-vegetable-37489 thoughts on where to document the new buf integration?
For code generation, we have dedicated pages for each language x protocol. It has worked well, kept things simpler
We could add a dedicated page specifically for Buf... But there is no category for that to go into
Instead, I'm thinking that we have a small section about Buf in each of the language specific pages. It really does not need to be much, basically how to activate the backend and how to run the goals.
Usually duplication is a bad thing, but in documentation, it can sometimes have merit
What do you think?
f
fast-nail-55400
04/15/2022, 3:40 PMwhat about a landing page for the protocol with links to the language-specific pages and then a subsection on the landing page for stuff like Buf?
n
narrow-vegetable-37489
04/15/2022, 4:13 PMHmm, yeah. I don't think Protobuf has enough going for it to justify having more than just a page. I do like the idea of some sort of landing page though that simply directs people to each language-specific page with some language-agnostic info on it as well (incl. Buf).
I think code generation in particular is a really cool feature in Pants that deserves some more lights on it - so maybe an "Integrations" or "Features" category/grouping in the docs menu with one of the pages being "Code Generation" could be an option, and then put Protobuf as a sub-page there. That would let us showcase code generation and other Pants features/selling points a bit more, right now it feels like some of them you have to stumble upon the docs to know they exist. Like if/when more languages support Lambda/Cloud Functions they could get sub-pages under some "Serverless" page in that category.
h
hundreds-father-404
04/15/2022, 4:40 PMYeah this is a tricky question... Right now, we group all integrations by language. We could instead have a top level integrations page: bundle all Protobuf together
My major project for this month is to re-organize our documentation. (a task I can do well with dictation while my collarbone is messed up)
I think for now, I will stick with having only the language specific pages and not do any bigger reorganization yet. There will be duplication, but that is acceptable for now.
It will take both of your feedback strongly into consideration with how to re-organize this month, though. Thank you so much!
🙌 1
w
witty-crayon-22786
04/20/2022, 10:17 PMmm, was just pointed to this thread.
imo, the language is the better top-level divider here (and buf is a bit of a special case because it deals directly with protobuf-the-language): i.e., we could have “python codegen” and “go codegen” pages, each having a table of the generators supported for them and any differences. but within a language, codegen should generally all be pretty similar (and if it isn’t: can we improve that in code?)
h
hundreds-father-404
04/20/2022, 10:19 PMMaybe. For Python, it helped a lot to have different pages for Thrift vs Protobuf. The semantics are different like that thrift generates INIT files for you
w
witty-crayon-22786
04/20/2022, 10:19 PMstructuring as a table helps to call out those differences though, rather than hiding them among a larger (potentially redundant) explanation
(table or w/e… doesn’t need to be literally a table)
h
hundreds-father-404
04/20/2022, 10:21 PMPart of my motivation with separate pages was that it seems likely some organizations will only use one protocol. So, if you are only using protobuf, it is noisy to have anything related to thrift on the page
And if you do use both protocols, both pages are pretty short as it is. It should not be that hard to navigate both
w
witty-crayon-22786
04/20/2022, 10:22 PMmaybe. but maintaining m*n redundant pages is a significant expense. calling out clearly which parts are general and which are code-generator specific seems much easier.