https://pantsbuild.org/ logo
Join Slack
Powered by
<@U023G1MP6JV> thoughts on where to document the ...
# development
h
@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
what 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
Hmm, 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
Yeah 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
mm, 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
Maybe. 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
structuring 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
Part 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
maybe. 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.
Open in Slack
PreviousNext
Powered by