jaimergp
commented
4 months ago Love this. The biggest concern is not breaking any existing URLs and anchors that might refer to existing content.
How we have addressed this so far:
- If there's a one-to-one correspondence between URLs (the same page with the same anchors just moved from one place to other), we can use the redirects defined in
docusaurus.config.js. - If different sections have moved to different pages, the original page can remain in place as an unlisted page with the old anchors pointing to the new URL and section. Example at https://github.com/conda-forge/conda-forge.github.io/blob/main/src/pages/announcements.md.
Another point is how sometimes the line between "For users" and "For maintainers" is not entirely clear. At least, I struggled while categorizing it during that experiment in the draft site. Maybe because I was trying to shuffle existing docs around, and didn't leave room for new content.
In that vein, if categorizing things in the filesystem is too restrictive, we can also leverage the custom sidebar setup (the paths and the categories match in this case, but they don't have to), and the document tags to label pages with certain information (for-beginners, easy, advanced, whatever).
cc @zklaus for awareness
h-vetinari
zklaus
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 in the context of the more tightly-scoped #2154:
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 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 with Diátaxis; a more detailed comparison is available below the fold.
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...? |