conda-forge / conda-forge/conda-forge.github.io
RFC: restructure website content, roughly following Diátaxis
- Dominant language
- JavaScript
- Stars
- 170
- Forks
- 320
- Avg merge
- 2d 10h
- Merged PRs (30d)
- 5
Description
There are several ongoing efforts to improve the conda-forge website, which has yielded the new website, status page, as well as some work around the infrastructure pages.
Additionally @jaimergp [wrote](https://github.com/conda-forge/conda-forge.github.io/issues/2154#issuecomment-2064124108) in the context of the more tightly-scoped #2154:
> 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 took that idea and came up with a rough draft of how the website could be structured (originally looking only at the infrastructure page, but I felt I needed a big picture view even for that). Some new content would have to be written, but mainly it is intended to reshuffle existing content into easily discoverable and more granular pieces.
As [Diátaxis](https://diataxis.fr/) intentionally aims at gradual transformation rather than big bang refactoring, this outline would likely change as we iterate, but I wanted to get people's thoughts on the rough strokes (and then discuss it in the core call), so we can agree on the overall direction and let people start chipping away at some first pieces.
This is based on looking at our current docs as well as @jaimergp's [experiment](https://cf-infra-docs.netlify.app/docs) with Diátaxis; a more detailed comparison is available below the fold.
```
Welcome
For users
└ ... # not in scope here
For maintainers
├ Tutorials
| ├ Generate a conda recipe # Using greyskull or whatever
| ├ Write your first recipe # Segue from first tutorial, make some changes
| ├ Submit your first recipe # Segue again, process for submission
| └ ...
├ How-to guides
| ├ Easy # the below is just a selection, obviously
| | ├ Read a recipe # Component overview, refer to in-depth explanation
| | ├ Rerender feedstock
| | ├ Test packages
| | ├ Deal with numpy
| | ├ Enable osx-arm64 # Same for arches
| | ├ Talk to the bots # refer to bot command reference page
| | └ ...
| ├ Medium
| | ├ Cross-compile
| | ├ Enable CUDA
| | ├ Multi-output recipes
| | ├ LTS branches
| | └ ...
| └ Emergencies
| ├ Patch repodata
| └ Mark a package broken
├ Understanding conda-forge # Explanation part of Diátaxis
| ├ Life-cycle of a package # essentially https://cf-infra-docs.netlify.app/docs/fundamentals/life-cycle/
| | └ ...
| ├ How a package gets built
| | ├ Compilation concepts # shared/static/etc.
| | ├ Environment roles # e.g. build: vs. host:
| | ├ Compilers # e.g. role of activation
| | ├ Global pinning
| | ├ Run exports
| | ├ Jinja functions
| | └ ...
| ├ How our bots work
| | ├ Migrations
| | ├ regro infrastructure
| | └ ...
| ├ Security
| | ├ Output validation
| | └ ...
| ├ Maintainer roles
| └ ...
├ Reference
| ├ Infrastructure # more in-depth discussion in #2154
| | ├ 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
| ├ Feedstock settings # conda-forge.yml, CBC, migrators
| ├ Glossary
| ├ Current pins # Auto-generated / subset?
| ├ Ongoing migrations # refer to status page
| └ ...
├ Miniforge
└ FAQ # separate section because questions cover both how-to & reference...?
```
Comparison with current docs and Diátaxis experiment
| | vs. [docs](https://conda-forge.org/docs/) | vs. [Infra Exp.](https://cf-infra-docs.netlify.app/docs/) | Comment |
|--------|--------|--------|--------|
| `Welcome` | == [here](https://conda-forge.org/docs/) | == [Welcome](https://cf-infra-docs.netlify.app/docs/) | |
| `For users` | == [here](https://conda-forge.org/docs/user/) | n/a | could surely be improved... |
| `└ ...` | | | ... but not in scope here|
| `For maintainers` | == [here](https://conda-forge.org/docs/maintainer/) | n/a | |
| `├ Tutorials` | partially [here](https://conda-forge.org/docs/maintainer/adding_pkgs) | == [Tutorials](https://cf-infra-docs.netlify.app/docs/tutorials/) | |
| `\| ├ Generate a conda recipe` | | | Using `greyskull` or whatever |
| `\| ├ Write your first recipe` | | | Segue from first tutorial,
make some changes |
| `\| ├ Submit your first recipe` | | ~= [placeholder](https://cf-infra-docs.netlify.app/docs/tutorials/submit-a-recipe/) | Segue again,
process for submission |
| `\| └ ...` | | | |
| `├ How-to guides` | distributed all over | == [How-to guides](https://cf-infra-docs.netlify.app/docs/howto/) | |
| `\| ├ Easy` | | | |
| `\| \| ├ Read a recipe` | | | Component overview,
refer to in-depth explanation |
| `\| \| ├ Rerender feedstock` | | | |
| `\| \| ├ Test packages` | | | |
| `\| \| ├ Deal with numpy` | roughly [here](https://conda-forge.org/docs/maintainer/knowledge_base/#building-against-numpy) | | |
| `\| \| ├ Enable osx-arm64` | roughly [here](https://conda-forge.org/docs/maintainer/knowledge_base/#apple-silicon-builds) | | Same for [arches](https://conda-forge.org/docs/maintainer/knowledge_base/#using-arch_rebuildtxt) |
| `\| \| ├ Talk to the bots` | | | refer to bot command
reference page |
| `\| \| └ ...` | | | |
| `\| ├ Medium` | | | |
| `\| \| ├ Cross-compile` | ~= [here](https://conda-forge.org/docs/maintainer/knowledge_base/#cross-compilation) | | |
| `\| \| ├ Enable CUDA` | ~= [here](https://conda-forge.org/docs/maintainer/knowledge_base/#cuda-builds) | | |
| `\| \| ├ Multi-output recipes` | ~= [here](https://conda-forge.org/docs/maintainer/knowledge_base/#multi-output-recipes) | | |
| `\| \| ├ LTS branches` | ~= [here](https://conda-forge.org/docs/maintainer/updating_pkgs/#maintaining-several-versions) | | |
| `\| \| └ ...` | | | |
| `\| └ Emergencies` | | | |
| `\| ├ Patch repodata` | | | |
| `\| └ Mark a package broken` | ~= [here](https://conda-forge.org/docs/maintainer/updating_pkgs/#removing-broken-packages) | | |
| `├ Understanding c-f` | not much | ~= [Fundamentals](https://cf-infra-docs.netlify.app/docs/fundamentals/) | "Explanation" part of [diataxis](https://diataxis.fr/) |
| `\| ├ Life-cycle of a pkg` | | == [here](https://cf-infra-docs.netlify.app/docs/fundamentals/life-cycle/) | |
| `\| \| └ ...` | | | |
| `\| ├ How a pkg gets built` | | | |
| `\| \| ├ Compilation concepts` | | | shared/static/etc. |
| `\| \| ├ Env. roles` | short [comment](https://conda-forge.org/docs/maintainer/knowledge_base/#placing-requirements-in-build-or-host) | | e.g. [`build:` vs. `host:`](https://github.com/conda-forge/staged-recipes/pull/24841#discussion_r1452946898) |
| `\| \| ├ Compilers` | partially [here](https://conda-forge.org/docs/maintainer/infrastructure/#compilers-and-runtimes) | | e.g. role of activation |
| `\| \| ├ Global pinning` | ~= [here](https://conda-forge.org/docs/maintainer/pinning_deps/) | | |
| `\| \| ├ Run exports` | ~= [here](https://conda-forge.org/docs/maintainer/pinning_deps/#specifying-run_exports) | | |
| `\| \| ├ Jinja functions` | | | |
| `\| \| └ ...` | | | |
| `\| ├ How our bots work` | | see [here](https://cf-infra-docs.netlify.app/docs/advanced/automation/) | |
| `\| \| ├ Migrations` | ~= [here](https://conda-forge.org/docs/maintainer/knowledge_base/#migrators-and-migrations) | | |
| `\| \| ├ regro infra` | | | |
| `\| \| └ ...` | | | |
| `\| ├ Security` | ~= [here](https://conda-forge.org/docs/maintainer/knowledge_base/#security-considerations-for-conda-forge-builds) | see [placeholder](https://cf-infra-docs.netlify.app/docs/advanced/security/) | |
| `\| \| ├ Output validation` | | | |
| `\| \| └ ...` | | | |
| `\| ├ Maintainer roles` | roughly [here](https://conda-forge.org/docs/maintainer/guidelines/) & [here](https://conda-forge.org/docs/maintainer/adding_pkgs/#maintainer-role) | | |
| `\| └ ...` | | | |
| `├ Reference` | all over | == [Reference](https://cf-infra-docs.netlify.app/docs/reference/) | |
| `\| ├ Infrastructure` | | ~same content split
somewhat differently | |
| `\| \| ├ Staged recipes` | | roughly [here](https://cf-infra-docs.netlify.app/docs/reference/infrastructure/staged-recipes/) | incl. teams |
| `\| \| ├ Compilers` | roughly [here](https://conda-forge.org/docs/maintainer/infrastructure/#compilers-and-runtimes) | | |
| `\| \| ├ Other core packages` | | | sysroots, CDTs, msys2, ... |
| `\| \| ├ CI Setup` | | | docker images,
conda-forge-ci-setup |
| `\| \| ├ CI providers` | | roughly [here](https://cf-infra-docs.netlify.app/docs/reference/infrastructure/services/) | |
| `\| \| ├ Global pinning` | ~= [here](https://conda-forge.org/docs/maintainer/pinning_deps/) | | +explain migrators |
| `\| \| ├ Feedstock evolution` | | | conda-smithy |
| `\| \| ├ Feedstock metadata` | | | graphs, feedstocks,
feedstock-outputs |
| `\| \| ├ Metadata corrections` | | | repodata-patches, admin-requests |
| `\| \| ├ Bot repos` | | | all things regro |
| `\| \| ├ Website` | | == [here](https://cf-infra-docs.netlify.app/docs/reference/infrastructure/website/) | |
| `\| \| └ ...` | | | |
| `\| ├ Bot commands` | ~= [here](https://conda-forge.org/docs/maintainer/infrastructure/#admin-web-services) | == [here](https://cf-infra-docs.netlify.app/docs/reference/bot-commands/) | |
| `\| ├ Feedstock settings` | mostly [here](https://conda-forge.org/docs/maintainer/conda_forge_yml/) | == [here](https://cf-infra-docs.netlify.app/docs/reference/feedstock-settings/) | `conda-forge.yml`, CBC, migrators |
| `\| ├ Glossary` | == [here](https://conda-forge.org/docs/glossary/) | == [here](https://cf-infra-docs.netlify.app/docs/reference/glossary/) | |
| `\| ├ Current pins` | | == [here](https://cf-infra-docs.netlify.app/docs/reference/pinnings/) | Auto-generated / subset? |
| `\| ├ Ongoing migrations` | | | refer to status page |
| `\| └ ...` | | | |
| `├ Miniforge` | | == [here](https://cf-infra-docs.netlify.app/docs/miniforge/) | |
| `└ FAQ` | ~= [here](https://conda-forge.org/docs/maintainer/maintainer_faq/) | | separate section because
questions cover both
how-to & reference...? |
Contributor guide
Assessment
This issue has not been assessed yet.