google / google/flax

Proposal: New RTD content structuring

Open
#2,627 4 comments 4 reactions 1 assignee Claimed by @marcvanzee View on GitHub
Priority: P2 - no schedule
Dominant language
Jupyter Notebook
Stars
7.3k
Forks
833
Avg merge
5h 11m
Merged PRs (30d)
5

Description

## Motivation

RTD has really improved a lot of the past half year (thanks a lot @cgarciae and @8bitmp3 -- this was all you!), but there are still a number of things that I think can be improved further.

The main problem is that I think the difference between "Guides", "Advanced Topics" and "Sharp Bit" isn't always very clear.

Some examples:

* "Dealing with module arguments" is in Advanced, but it could also be a sharp bit or a guide. I am not sure if people know where to look when they want to find something.
* "How to contribute" and "The Flax Philosophy" are both under "Advanced", but I am also not sure if that is the right place.
* "Upgrading my codebase to Optax": is this advanced? I am not sure. When is something advanced?
* "Getting Started" is a the top level, but it seems to be a guide?
* Some guides are very long (e.g., "Flax Basics"), while others are much shorter and rather code snippets. What do we want from a "guide"?

Another issue is that I think it is too difficult right now for users to get started with Flax in OS. Our documentation only explains how to install Flax locally (basically just `pip install flax`), but it is not easy to find how to set it up on a Cloud machine, which I think is what practically everyone in OS would like to do.

## Proposal

Here is a proposal for an alternative structuring of our RTD:

* **Tutorials** are end-to-end, long-form guides where we go through an entire example. I think tutorials generally consist of multiple pages. For instance: our "Flax Basics" could be separate into: JAX basics, Flax Modules, Optimization, and Training. Then we could have another tutorial in the future called "NLP with Transformers", containing pages for input pipeline, model code, training code, etc).
* **Flax Bites** are comparable to [Pytorch recipes](https://pytorch.org/tutorials/recipes/recipes_index.html); "actionable examples of how to use specific PyTorch features, different from our full-length tutorials." In essence, bites are short tutorials.
* **Developer notes** are notes for people who are writing code in Flax and want to understand it in more detail. This is similar to "Advanced Topics" right now.

Of course it may not always be clear when something is a tutorial or when it is a bite. But I think a tutorial is really something that explain an entire example end to end, while a bite is about a specific topic.

### Proposed Navigation Layout

We could structure the navigation as follows:

* **[Get started]**. This is the main entry point for OS users. I think it should explain how to setup Flax, and how to run it somewhere else than on your local machine, since this is what practically everyone doing DL would like to do. I think it should **not** yet explain any Flax internals, that we can put in a tutorial. So it should explain:
* *start locally*: how to run Flax on your machine
* *start via Colab*: very simple, but worth explaining how to connect to GPUs and TPUs.
* *start via Google Cloud*: @andsteing wrote some scripts and there is some Google Cloud documentation on JAX. We should at least link to it or just explain the steps here.

* **[Tutorials]**. These contain both long-formed tutorials and bites.
* *Flax Bites*: * think the bites should be searchable, but they don't have to all be in the LHS navigation menu (otherwise it will get very long). So if users click on "Flax Bites", they get maybe a list of bites or a search bar, or something more fancy (similar to what [Pytorch has](https://pytorch.org/tutorials/recipes/recipes_index.html)).
* *Introduction to Flax*: this can contain "JAX for the impatient" and "Flax Basics" (I propose we merge the content of the current "Getting Started" with "Flax Basics")
* *Transfer learning": this could perhaps also be tutorial.

* **[Developer documentation]**: More or less the same as what is now in advanced topics.
* *[Developer notes]*: Same as currently "Advanced Topics"
* *[Flax - the sharp bit]*: Short points of things that you should be aware of when using Flax, possibly linking to other pieces of documentation.
* *[API Reference]*: Same as before

Please let me know what you think, these are just some directions we could go in, but very curious to hear what your thoughts are as well!

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.