mlverse
Reorganizing the docs
I was looking at more places to help improve the torch docs (all of https://torch.mlverse.org/), and I think by far the most useful thing would be to clean up the organization of the docs. Right now there is lots of content spread all over, and the important stuff isn't necessarily highest in the hierarchy. Today, the page is split up like this:
- Homepage - details of the other packages
- Get started - set of three tutorials
- Get technical - more examples
- Use torch - a five part tutorial
- Resources - links to external things that could be useful
- Docs
- Articles - details of using torch based on vignettes
- Examples - some sparse examples
- Reference - extremely useful and important list of all functions
- Changelog
I think there are a few issues with this layout, including:
- "examples" meaning things that are just code you can run, documented single examples, and full on tutorials are split into multiple places. It's not clear why some examples are in one place and not others, and it's not clear what a person should start with
- some really important content that most users care about, like the reference, is nested deeply and not easy to find
- There isn't a clear "here is the first page you should read to do a hello, word torch model"
- For reasons I assume are due to using packagedown, the navbar changes depending on if you're on the /docs page, which makes it hard to navigate.
I think it would be a good idea to rearrange the pages a bit (even if it means changing where things live on the backend for packagedown reasons), into something like the following:
- Homepage - the exact same as today
- Examples
- Quickstart - new, a single example that just shows using torch in a few lines
- Full torch tutorial - what is currently called "use torch"
- Examples by topic - these are what is currently called "get technical"
- Articles - the same as the existing articles section
- Reference - the same as the existing reference
- Get help
- External resources - same as the existing resources page, including a link to torch-learnr
- Contact - links for how to make requests (probably github and stack overflow)
- Changelog - same as today
Removed from the website would be:
- https://torch.mlverse.org/start/ - the three tutorials listed here would get merged into other pages, like the dataloader one
- https://torch.mlverse.org/docs/articles/examples - these examples are pretty empty and I think the other examples do a better job
The benefits of this layout are
- Now things are coalesced--the examples are all in one area for instance
- All the important stuff can be seen from a consistent top navbar
- It should be easier for new users to understand where to go (probably "quickstart")
I am happy to take on doing this docs reorg! My questions are (1) would y'all be okay with this broadly? (2) do you have thoughts on the particular layout I proposed? This is somewhat similar to what we did for the Saturn Cloud docs and I've been pretty happy with it.
Hi @jnolis,
Thanks very much for the comments.
I agree with all the changes broadly. You are completely right that 'content spread all over, and the important stuff isn't necessarily highest in the hierarchy'. Docs is probably one of the most important parts of the project and I agree the current state is really confusing.
Maybe I can explain how we ended up here: the initial idea was that 'torch.mlverse.org' should be the ecosystem homepage, so it should have tutorials that can include the full suite of packages like, torchvision, luz and torchdatasets. On the other hand, torch.mlverse.org/docs is the pkgdown website for the torch R package, so content here should be exclusive to torch or just the reference page. Turns out it's not very easy to separate what's content that exclusive of torch and content that is important for the broad ecosystem.
That leads to (2). I think we should consider if, for example, the 'Articles' section should list the Luz articles as well, like: https://mlverse.github.io/luz/articles/get-started.html Luz has also many code only examplethat many users currently can't find: https://mlverse.github.io/luz/articles/examples/index.html Also if the 'Reference' should also display the reference for other packages in the ecosystem. What do you think?
The current website workflow is:
torch.mlverse.org is a blogdown website built from the blogdown branch: https://github.com/mlverse/torch/tree/blogdown
torch.mlverse.org/docs is the pkgdown website - its built in CI and copied directly into the blogdown static directory.
I'd prefer keeping the articles source in the main repository for each package. In my experience, it's too easy to break/ don't update them when they live in a different repository and are not constantly tested in the CI. That's not necessary for the more extensive tutorials as they usually take too much time to run and would probably be skipped in the CI.
Ah yes, that makes sense as to how the docs got to where they are. I like the idea of merging the ecosystem hompage and torch page into one, and then having that give clear references to the other package. So as you suggested it would become:
- Torch documentation
- Homepage - the exact same as today including links to the other package packagedown pages
- Examples
- Quickstart - new, a single example that just shows using torch in a few lines
- Full torch tutorial - what is currently called "use torch"
- Examples by topic - these are what is currently called "get technical"
- Articles - the same as the existing articles section
- Reference - the same as the existing reference, except add clear references to the other packages
- Get help
- External resources - same as the existing resources page, including a link to torch-learnr
- Contact - links for how to make requests (probably github and stack overflow)
- Changelog - same as today
- Luz packagedown page...
- torchvision packagedown page...
- ...
This would still keep the articles about each package within the package itself, and would remove the ambiguity because most people assume the torch homepage is focused on the package more than the ecosystem.
Cool @jnolis ! I think this makes a lot of sense! In this case, It seems that a possible solution would be to:
- deprecate the blogdown website and have the pkgdown webiste only
- move the home page information to the home page of the pkgdown website - keeping the design might be hard, but I think it's fine if we don't keep it.
- move tutorials to the main repository, probably as usethis::use_article instead of vignettes so they don't go to CRAN.
- Re-organize the toolbar using the pkgdown.yaml file
What do you think? Thanks very much!
I think that sounds good! I'm not an expert in pkgdown or blogdown (I make all my websites in base hugo), so I'll spend a little time with this seeing how much we can coerce the desired page into the pkgdown site. I'll get started on this over the next week or so
Hi! Just an update that I've been working on this, but I'm having a bit of trouble getting the pkgdown package to do what I want. I'm making progress it's just taking more time than I expected! Things like getting the css to work nicely is especially tricky.
Sorry @jnolis I was mostly offline last week for vacations. Thanks for the update! Let me know if I can be of any help!