-
-
Notifications
You must be signed in to change notification settings - Fork 268
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
RFC: restructure website content, roughly following Diátaxis #2164
Comments
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:
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 |
Yeah that would likely be a large part of the challenge - for now I was happy to draw outlines unencumbered by that though 😅
When I was looking at this, I kind of saw the utility of the existing separation, i.e. someone wanting to just consume packages has a very different set of concerns than someone trying to maintain a feedstock. Consequently, I had descoped the "for users" part in my draft, but I agree with you that the separation is not obvious, and likely harmful in terms of having an easy "on ramp" for turning package consumers into conda-forge contributors. It would be nice if we can smoothen that transition somehow. |
My thoughts exactly! |
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
Welcome
For users
└ ...
For maintainers
├ Tutorials
| ├ Generate a conda recipe
greyskull
or whatever| ├ Write your first recipe
make some changes
| ├ Submit your first recipe
process for submission
| └ ...
├ How-to guides
| ├ Easy
| | ├ Read a recipe
refer to in-depth explanation
| | ├ Rerender feedstock
| | ├ Test packages
| | ├ Deal with numpy
| | ├ Enable osx-arm64
| | ├ Talk to the bots
reference page
| | └ ...
| ├ Medium
| | ├ Cross-compile
| | ├ Enable CUDA
| | ├ Multi-output recipes
| | ├ LTS branches
| | └ ...
| └ Emergencies
| ├ Patch repodata
| └ Mark a package broken
├ Understanding c-f
| ├ Life-cycle of a pkg
| | └ ...
| ├ How a pkg gets built
| | ├ Compilation concepts
| | ├ Env. roles
build:
vs.host:
| | ├ Compilers
| | ├ Global pinning
| | ├ Run exports
| | ├ Jinja functions
| | └ ...
| ├ How our bots work
| | ├ Migrations
| | ├ regro infra
| | └ ...
| ├ Security
| | ├ Output validation
| | └ ...
| ├ Maintainer roles
| └ ...
├ Reference
| ├ Infrastructure
somewhat differently
| | ├ Staged recipes
| | ├ Compilers
| | ├ Other core packages
| | ├ CI Setup
conda-forge-ci-setup
| | ├ CI providers
| | ├ Global pinning
| | ├ Feedstock evolution
| | ├ Feedstock metadata
feedstock-outputs
| | ├ Metadata corrections
| | ├ Bot repos
| | ├ Website
| | └ ...
| ├ Bot commands
| ├ Feedstock settings
conda-forge.yml
, CBC, migrators| ├ Glossary
| ├ Current pins
| ├ Ongoing migrations
| └ ...
├ Miniforge
└ FAQ
questions cover both
how-to & reference...?
The text was updated successfully, but these errors were encountered: