Skip to content
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

Docs Revamp #2174

Closed
shivance opened this issue Feb 2, 2023 · 5 comments
Closed

Docs Revamp #2174

shivance opened this issue Feb 2, 2023 · 5 comments

Comments

@shivance
Copy link

shivance commented Feb 2, 2023

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
Copy link
Member

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

@mcabbott
Copy link
Member

mcabbott commented Feb 3, 2023

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.

@shivance
Copy link
Author

shivance commented Feb 3, 2023

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

We can also take a look at this

@shivance
Copy link
Author

shivance commented Feb 6, 2023

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

@mcabbott
Copy link
Member

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.

@shivance shivance closed this as completed Jun 4, 2023
@shivance shivance closed this as not planned Won't fix, can't repro, duplicate, stale Jun 4, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants