Add Flux Overview to basics.md

[batate]

As requested in issues/comments, this documentation PR adds an overview for Flux:

• I described the overall process that Flux uses: data/model/train/verify.
• I created an example that simulates a single Wx+b line.
• I made some minor tweaks to the other documentation.
• I structured the outline headings so that this model can be easily skipped

If you like this direction, I can add:

• A Flux quick start that defines a prediction of an XOR operator (one example, around 10-20 loc)
• A link to quick-start directly from the overview
• Transition into the gradient descent from the quick start

PR Checklist

• Tests are added
• Entry in NEWS.md
• [ x] Documentation, if applicable
• API changes require approval from a committer (different from the author, if applicable)

[DhairyaLGandhi]

Haven't gone through the PR fully, but left a couple thoughts. Thanks for looking into this! This might want to be it's own little section, because we want to make sure the flow of the document is natural and targeted.

[ToucheSir]

Thanks for taking this on! A quick first pass from me:

[batate]

I am almost done with these updates, and another tweak to extract this flow into another section. I also want to do a Flux quickstart for those already familiar with ML math and Julia, a rapid introduction of all Flux concepts and a quick pointer to the model zoo. Sorry it's going slowly; my writing schedule is intense.

Can someone guide me through where to use doctests, and what the markdown should look like if I want to show Julia console output, but not in a doctest? Right now, anything with random content breaks, as do the predictions. Rather than:

jldoctest basics

what should I use to mark up code blocks?

[DhairyaLGandhi]

Normal code blocks and triple backtick (```) blocks should do

[DhairyaLGandhi]

We should typically only have doctests for features from the FluxML ecosystem and have predictable outcomes (so nothing that uses random output, for example)

Documenter understands to parse julia> as a simulated repl session.

[batate]

So

```julia>

and not

```julia> basics

?

[DhairyaLGandhi]

Yup

[batate]

I make the suggested changes, and broke the overview into its own section. Eventually, the overview will contain

Flux Overview

Flux Gentle Introduction (this prose)

Flux Quick Start (a much quicker overview and specific links to appropriate quick start resources)

[darsnack]

Looking pretty good. One suggestion I have is to add a section on "decoding" the output of a model (i.e. the difference between loss and accuracy). The current problem in the tutorial being regression may not be best suited to this. So, we could save this for a different tutorial.

[batate]

Looking pretty good. One suggestion I have is to add a section on "decoding" the output of a model (i.e. the difference between loss and accuracy). The current problem in the tutorial being regression may not be best suited to this. So, we could save this for a different tutorial.

Great idea. I agree that it belongs elsewhere.

[batate]

This review flow is unfamiliar to me. Let me know if I need to do anything else. Thanks for your patience.

[darsnack]

Looks ready to merge, but I just wanted clarification on the

```julia>

syntax. I've never seen that before. If I understand the desired behavior correctly, then the syntax you want is @repl

[batate]

Looks ready to merge, but I just wanted clarification on the

syntax. I've never seen that before. If I understand the desired behavior correctly, then the syntax you want is @repl

Great. This doc system is new to me. I adjusted the pull request to look like the examples I found here ... see the repl examples within the file.

I did not want to use @repl because that would run the examples again, leading to new values, and potentially rendering the prose invalid (e.g. a loss that goes up for one epoch). So I landed on the compromise of julia instead of @repl. It works OK, for the most part. Hope that's OK.

[DhairyaLGandhi]

Just wrapping it in the code blocks is fine, just need the Julia prompt to be on the new line, no need for the at-repl annotation, that's picked up automatically

[darsnack]

Yeah, we don't use @repl in the Flux docs. What you have right now works. I left some final comments.

[doppioandante]

As a newbie to Flux and machine learning in general, thanks for this. I skimmed through it and it is pretty clear.

[batate]

I dropped the julia annotations (julia to ) and added a review.

When this one is ready, I am happy to take on a quick start if we like the direction of these docs.

[darsnack]

Great, thanks for your work @batate! Will merge once the checks pass.

[ToucheSir]

Couple last-minute comments from me, if you don't mind. Mostly following up on earlier comments that I didn't get notifications for when they became "outdated" in the churn.

[ToucheSir]

Last minute comment, sorry! #1579 (comment)

[batate]

I took another shot at the prose because our discussions are a clue that the readers will also have trouble with the concept. Here's the main bit:

---

julia> model.b
1-element Array{Float64,1}:
 0.0

Under the hood, a dense layer is a struct with fields W and b. W represents a weight and b represents a bias. There's another way to think about a model. In Flux, models are conceptually predictive functions:

julia> predict = Dense(1, 1)

Dense(1, 1) also implements the function σ(Wx+b) where W and b are the weights and biases. σ is an activation function (more on activations later). Our model has one weight and one bias, but typical models will have many more. Think of weights and biases as knobs and levers Flux can use to tune predictions. Activation functions are transformations that tailor models to your needs.

---

let me know if this is takes us in a better direction.

[batate]

Great, thanks for your work @batate! Will merge once the checks pass.

You are quite welcome. I plan to be around for a while, and this looked like a good place to cut my teeth on the process and the community. Any idea why the build failed? It didn't look like it had anything to do with the commit.

[darsnack]

Not sure, but the tests are passing now.

[darsnack]

I think we settled on a good compromise for now. We can fine tune at a later date as needed.

Will merge once the checks pass.

[darsnack]

bors r+

[bors]

Build succeeded:

• buildkite/flux-dot-jl