[Matplotlib-devel] Documentation

[Matt Arcidy]

Good points.  I wonder if tagging is better with a search/filter than
only categorization.  Someone could filter/search for tutorials which
only use arithmetic and basic python, or grab all tutorials/examples
that use Axes.xlim, etc.  I guess that's for later though.

I don't know a good way to classify python as
beginner/intermediate/expert. Having taught all those levels, maybe
you have clear insight into that?

Do you have ideas for the survey, how, what etc?  That's a great idea.
I'd love to get as many profiles as possible up front.

I'm attempting to get a handle on all the functions used in the
examples/tutorials (note below). I'd like to categorize the
functions/concepts used for them as well.  Will need categories first
of course.

Those are 3 pretty good tasks I think:
1) classify python by skill level
2) survey ideas
3) gather data on current tutorials/examples and rough categorization

This is just a list, I'm not one to assign anything.  I'll work on
whatever needs to get done.

All:
I would like to be able to go through all the example/tutorial scripts
and pull out which matplotlib modules/functions/objects are used in
each script, just top level.  Since they are scripts and not modules,
I cannot seem to get reflection to work like a for a module (so far
anyways).  If anyone has a good tool I would greatly appreciate it.


Thanks,
-Matt


On Thu, Feb 8, 2018 at 8:15 AM, Hannah <story645 at gmail.com> wrote:
> 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
>
>
>