[Matplotlib-devel] Documentation

[Hannah]

Hi Matt,
I'm super psyched that you're onboard and totally agree with you on the
importance of identifying audience. I think that's a lot of where the docs
really struggle because the audience is very broad.

For example, I introduce matplotlib a lot to the following audiences who I
don't think you've mentioned yet:

high school students
-little to no programming classes
-a summer REU
-only know about the plots they've seen in their science class

humanaties masters and graduate students
- little/no programming experience
- frame of reference for visualization is usually journalism viz like New
York Times or art installations.
- often don't have or forgot the vocabulary around  scientific and
statistical plots (what is a measurment, scale, etc)

Computer Science students
- undergrad through grad
- taking a visualization course
- have lots of programming experience, but not necessarily in Python
- want to make highly information dense plots or dashboards


And I really would love a survey of the community to get an even better
sense of who is using matplotlib.

-Hannah

On Feb 8, 2018 3:30 AM, "Matt Arcidy" <marcidy at gmail.com> wrote:

Hi All,

Please forgive the presumption of pulling this topic out of from the
meeting thread especially as this is also in a self-introduction email.

I want to help with the documentation effort.  I read Tom's article in
numfocus and the desired skillset rang true.  I have 10ish years experience
writing tech docs, a few 100+ pages.   I write creatively, and I am still
somewhat new to matplotlib.  I am happy to work in any capacity, though i
am most interested in cranking out the first draft of the book.

I have looked into the available documentation over the past month+ so I
could come with understanding and ideas, some of which I hope are actually
good.

Both the meeting thread and Tom requested ideas for reorganizing the
tutorials and examples as a place to start, so I'll throw one out: explicit
definition of an audience, something to which all the documentation can
adhere.

Right now the tutorials are leveled as beginner, intermediate, and expert,
which is great, but it's not clear what that means.  Explicitly defining
the required skill sets, while not perfect, will allow sorting of concepts
and people into each bin.

As an example, (please excuse the contrivence):

Laura
- Sophomore in college
- dead set on being a data scientist
- 2 programming classes in python
- never used any kind of CAD software ever (i.e. does not have any concept
of a plot beyond a line on graph paper)

Xian
- 1 week away from Zoology PhD dissertation, under a deadline
- Has used R and Matplotlib to create very basic plots for papers
- Wants to create a plot with species heart size over adult weight, with
the marker being a jpg of the species' actual heart, beating at the actual
species' heart rate on the plot.

Ayah
- Post Doc or professional
- 10+ years of plotting experience using various packages but not matplotlib
- has funding to contribute significant functionality, but needs to get up
to speed on everything now

Obviously this is just beginner, intermediate, expert, but they can be
explicitly targeted/taught based on their skill level.  Laura needs
hand-holding, Xian needs a great API reference, Ayah needs a mosaic of
everything and a good architecture map.

In the same vein as above, learning paths through the tutorial documents.
There are some separable plotting skills, like visually designing the plot,
animation, application development, matplotlib development...etc. Each
skill could have beginner/intermediate/expert level tutorials which
progress naturally, creating a learning tract for each skill.  Skills can
be stacked to flow into specific roles.

Looking at this from outside, the best part about this project is all the
information is already there. I have more ideas to dump on you, but I'll
postpone until I have a better understanding of where I can fit.

Thanks!

_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel at python.org
https://mail.python.org/mailman/listinfo/matplotlib-devel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/matplotlib-devel/attachments/20180208/186fcf85/attachment.html>