Open h-vetinari opened 6 months ago
Last year, I experimented with how DiΓ‘taxis would apply to our docs in https://cf-infra-docs.netlify.app/docs. Some of the docs written for that experiment are being migrated over to our new website. @zklaus is almost finished, I think, with that effort.
I fully support the splitting. Here are some unordered thoughts that might make sense along with these efforts:
Also I think we need to distinguish between the infra that supports running a single build job, and the infra that supports orchestrating build jobs and automation. The line gets blurry at times, but I think it's worth trying it.
It is worth noting that we link to the admin bot requests all over the place. So if there is some way to forward the old links to whatever new page they live on, that would be quite helpful
Last year, I experimented with how DiΓ‘taxis would apply to our docs in https://cf-infra-docs.netlify.app/docs. Some of the docs written for that experiment are being migrated over to our new website. @zklaus is almost finished, I think, with that effort.
That looks very nice! I think we should not only take over the content, but also start structuring things in a similar way.
I think it would be beneficial to have the "life cycle" published as a standalone documentation entry because it gives a big picture of the whole infra. And then more details can be filled in in specific pages.
Sounds great - i.e. a big overview that branches off into separate little topic pages. I think in terms of diataxis quadrants that would be "Explanation" AFAICT, and very useful at that. We're lacking in that category a bit IMO (e.g. people struggle a lot with understanding the different roles of build:
& host:
environments; I have been wanting to write something up about that for a long time).
Hm, this turned out to be a way deeper rabbit hole than I wanted to dive into π
First, a proposal only for Reference:Infrastructure
(topic of this issue):
[...]
β Reference
| β Infrastructure
| | β Staged recipes # including teams
| | β Compilers
| | β Other core packages # sysroots, CDTs, msys2, ...
| | β CI Setup # docker images, conda-forge-ci-setup
| | β CI providers
| | β Global pinning
| | β Feedstock evolution # conda-smithy
| | β Feedstock metadata # graphs, feedstocks feedstock-outputs
| | β Metadata corrections # repodata-patches, admin-requests
| | β Bot repos # all things regro
| | β Website
| | β ...
| β Bot commands
| β ...
β ...
In order to orient myself, I however had to look at the bigger picture, so here's a suggested page structure based on the existing docs and the @jaimergp's experiment:
I really like this! One of the great things about DiΓ‘taxis is that it's explicitly build to not force you to do everything in one fell swoop. So moving in this direction with a plan as posted by @h-vetinari as a general guideline to follow sounds great to me.
With #2158, my transfer of content into the infrastructure page will be concluded, so I am all for moving forward in the proposed direction.
With #2158, my transfer of content into the infrastructure page will be concluded, so I am all for moving forward in the proposed direction.
This was merged earlier today. So it sounds like this issue is wide open
I opened a more broadly-scoped issue about the overall structure proposed above in #2164. I'll bring it up in the core call this week to see if people are on board with the overall direction. Once we have a Reference
section, it would be easier to move things, I think.
I'm looking at our infrastructure page, and it's pretty long and unwieldy.
I think it should be split up, possibly into several different pages. At the very least, I'd like to split it into stuff that's recipe-relevant (compilers, sysroot, CDTs), and stuff that regular maintainers need much less often (website, metadata, CI setup, etc.).
Other possible things that might deserve their own pages:
Thoughts @conda-forge/core?
CC @zklaus for recent efforts on these pages.