Omnibus documentation updates for v0.9

[mwaskom]

No description provided.

[codecov]

Codecov Report

Merging #1465 into master will decrease coverage by 0.01%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##           master    #1465      +/-   ##
==========================================
- Coverage    94.2%   94.18%   -0.02%     
==========================================
  Files          15       15              
  Lines        4486     4491       +5     
==========================================
+ Hits         4226     4230       +4     
- Misses        260      261       +1

Impacted Files	Coverage Δ
seaborn/regression.py	97.01% <ø> (ø)	⬆️
seaborn/categorical.py	96.44% <100%> (-0.25%)	⬇️
seaborn/basic.py	99.46% <100%> (ø)	⬆️
seaborn/axisgrid.py	94.73% <100%> (ø)	⬆️
seaborn/palettes.py	96.82% <100%> (+0.03%)	⬆️
seaborn/rcmod.py	99.05% <100%> (+1.88%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 1f40c42...1d0009c. Read the comment docs.

[chris1610]

Like I said in my tweet, I really like the new intro. It does a good job of orienting people so thanks for all that hard work. I know it is really challenging to write docs!

Here are a few observations that I noted as I went through it:

• In your first relplot example, I think it would be easier for people to follow if you let them know what relplot stood for. Something like "All of this was accomplished using a single call to the seaborn function relplot(). This function name is short for 'relationship plot' and allows the user to quickly plot scatter and line plots with multiple variables." I think giving this hint will help orient new users. I suspect most will know what a line or scatter plot is but there's a bit of mental translation we want to make with relplot.

• In the "dots" line plot example, I recommend showing the first 5 rows of data as a table like you do at the end of the page for the "tips" data. The "tips" data is a little more self-explanatory (in the first example) but I think the dots data needs to be shown in order for the plot to make since. I know that I went back and forth with the dots lineplot before I understood what it was telling me.

• When you introduce the "kind" parameter, I would expand a bit for relplot. Something like this: ' Some seaborn functions have a convenient kind parameter to let you easily swap the visual representation of the data. For relplot, the default is "scatter" but you can also use "line" to create a line chart.'

• For the statistical fmri plot, it might be good to show the first 5 rows of data as well. It's not quite clear to me how the data is being averaged. Seeing the table might make it more intuitive.

I like the work you put into figure-level vs axes-level functions. That is an important distinction that takes some time to sink in. I think you captured it well.

My final thought is that you did not spend much time talking about color palettes. I know that's a huge part of seaborn's appeal. An example of creating and using palettes might be nice. The page is getting long so I'll respect the decision if you think it's too much to add at this point.

Once again, thanks for doing all this work!

[mwaskom]

Thanks a lot, @chris1610, all great suggestions.

[mwaskom]

I know that I went back and forth with the dots lineplot before I understood what it was telling me.

Part of the reason this is confusing ATM is probably that work on adding subtitles to legends with multiple semantic variables is not yet complete (#1440)