Docs Revamp

[kanpuriyanawab]

Motivation and description

#2105

Having contributed to Metalhead and gathering some experience in Flux, I realise that flux needs a lot of documentation and more How Tos. While #2105 described the entire roadmap... What is the immediate item of action where I can start to contribute towards documentation improvement?

I believe that improving docs will make me understand flux more deeply

[ToucheSir]

We don't have such a fine-grained priority list, but have a look at all the issues with the documentation label.

[mcabbott]

One thing you can do is to flag things you find unclear / confusing on the first pass. These can be hard to see for those who've been involved too long.

In the manual, of the section now called "Guide" I think the last three sections (GPU, Saving, Performance) are over-due for a re-write. But they intersect with functional changes (like #1907, #2156) so it may be too soon to try.

It would be nice to have useful tutorials. Besides being out of date, much of what's in http://fluxml.ai/tutorials/ isn't very helpful.

[kanpuriyanawab]

@mcabbott @ToucheSir several medium blogs can be adopted as well this and this

We can also take a look at this

[kanpuriyanawab]

Is there a specific topic Flux would like to have a tutorial on, @ToucheSir @mcabbott ?

[mcabbott]

I think the most urgent place which needs attention is really the model zoo. In the past we had many examples which look like this:

https://github.com/FluxML/model-zoo/blob/master/vision/conv_mnist/conv_mnist.jl

and they got expanded into pages like this, by adding words:

http://fluxml.ai/Flux.jl/stable/tutorials/2021-02-07-convnet/

We shouldn't do that, it's not helpful. And it goes out of date easily.

Instead, I think that whole example should be under 50 lines. It should be as close to self-explanatory as possible. It should be made easy to step through at the REPL to try out the bits you don't follow. No @kwdef structs, no TensorBoardLogger, 1/4 as many functions.