matplotlib user guide

hi matplotlib developers

I have been considering the matplotlib user guide structure and it
has occured to me that there are two user guides interleaved here:
  1. Introduction for new users
  2. Library tour for developers

I think that this structure makes it challenging for new users to
benefit from the user guide as much as they could.

I would like to see the user guide separated into two sections, with
the two different audiences in mind. I feel this would enable new
users of the library to have a more targeted introduction to some of
the neat features without getting bogged down in details they are
unlikely to need (or comprehend).

I am very happy to have a go at this and put up a set of suggested
changes but I would value input from the community on this approach and
my category suggestions before I submit a pull request.

many thanks
mark

For the record, I’ve spoken to Mark about this face-to-face in the past, and I think he has some great ideas about how the user guide should look.

Personally I would agree that the user guide is currently not targeted enough (it takes 3 pages full of text before getting to a simple plt.plot() ) and even then, I don’t think it is sympathetic enough to really new users. Clearly matplotlib’s success shows that the documentation must be doing something right, but I think the user guide could definitely be improved.

Mark, from what I remember your changes were along the lines of moving sections around, and splitting some sections into beginner & advanced pages. I think detailing a few examples of the types of changes you have in mind might help us to have a bit more clarity on what you are proposing.

Thanks for getting involved in improving the docs!

···

On 25 September 2013 09:19, mark <markh@…1166…> wrote:

hi matplotlib developers

I have been considering the matplotlib user guide structure and it

has occured to me that there are two user guides interleaved here:

  1. Introduction for new users

  2. Library tour for developers

I think that this structure makes it challenging for new users to

benefit from the user guide as much as they could.

I would like to see the user guide separated into two sections, with

the two different audiences in mind. I feel this would enable new

users of the library to have a more targeted introduction to some of

the neat features without getting bogged down in details they are

unlikely to need (or comprehend).

I am very happy to have a go at this and put up a set of suggested

changes but I would value input from the community on this approach and

my category suggestions before I submit a pull request.

many thanks

mark


October Webinars: Code for Performance

Free Intel webinars can help you accelerate application performance.

Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most from

the latest Intel processors and coprocessors. See abstracts and register >

http://pubads.g.doubleclick.net/gampad/clk?id=60133471&iu=/4140/ostg.clktrk


Matplotlib-devel mailing list

Matplotlib-devel@lists.sourceforge.net

https://lists.sourceforge.net/lists/listinfo/matplotlib-devel

Thanks for the interest. I agree there's lots that can be done to improve it.

You may want to familiarize yourself with MEP10 ( https://github.com/matplotlib/matplotlib/wiki/Mep10) though that mainly deals with docstrings and not the narrative documentation.

Perhaps as a starting point, you'd want to write a MEP with your specific proposals -- maybe as a set of guidelines for how the docs should be laid out (with a few concrete examples of such changes, but without going through the laborious process of making all such changes). The nice thing about writing a MEP is that then we can point other people who want to help out to it and say "this is what we're trying to do", rather than the burden of all of the work being on just a single person. At least that's the idea :wink:

Mike

···

On 09/25/2013 04:19 AM, mark wrote:

hi matplotlib developers

I have been considering the matplotlib user guide structure and it
has occured to me that there are two user guides interleaved here:
   1. Introduction for new users
   2. Library tour for developers

I think that this structure makes it challenging for new users to
benefit from the user guide as much as they could.

I would like to see the user guide separated into two sections, with
the two different audiences in mind. I feel this would enable new
users of the library to have a more targeted introduction to some of
the neat features without getting bogged down in details they are
unlikely to need (or comprehend).

I am very happy to have a go at this and put up a set of suggested
changes but I would value input from the community on this approach and
my category suggestions before I submit a pull request.

many thanks
mark

------------------------------------------------------------------------------
October Webinars: Code for Performance
Free Intel webinars can help you accelerate application performance.
Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most from
the latest Intel processors and coprocessors. See abstracts and register >
http://pubads.g.doubleclick.net/gampad/clk?id=60133471&iu=/4140/ostg.clktrk
_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel

--
                    _

\/|o _|_ _. _ | | \.__ __|__|_|_ _ _ ._ _
>>(_| |(_|(/_| |_/|(_)(/_|_ |_|_)(_)(_)| | |

http://www.droettboom.com

hi matplotlib developers

I have been considering the matplotlib user guide structure and it
has occured to me that there are two user guides interleaved here:
   1. Introduction for new users
   2. Library tour for developers

I think that this structure makes it challenging for new users to
benefit from the user guide as much as they could.

I would like to see the user guide separated into two sections, with
the two different audiences in mind. I feel this would enable new
users of the library to have a more targeted introduction to some of
the neat features without getting bogged down in details they are
unlikely to need (or comprehend).

I am very happy to have a go at this and put up a set of suggested
changes but I would value input from the community on this approach and
my category suggestions before I submit a pull request.

Mark,

There is no doubt that the documentation can be improved, both via changes in organization and wording, and by adding missing parts. I'm happy to see you work on this, and look forward to the next increment of detail regarding your strategy.

Eric

···

On 2013/09/24 10:19 PM, mark wrote:

many thanks
mark

------------------------------------------------------------------------------
October Webinars: Code for Performance
Free Intel webinars can help you accelerate application performance.
Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most from
the latest Intel processors and coprocessors. See abstracts and register >
http://pubads.g.doubleclick.net/gampad/clk?id=60133471&iu=/4140/ostg.clktrk
_______________________________________________
Matplotlib-devel mailing list
Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel

Many thanks for the feedback.

So ,my first cut was to segregate the user guide by topic. Below is
the summary I had in mind for an Introduction for New Users.

Hopefully this gives a flavour of what I have in mind.

I will attempt to put this into practice and post again when I have a
user guide coded that might work in my view.

mark

Introducing Plotting with Matplotlib

    Pyplot tutorial
        Controlling line properties
        Working with multiple figures and axes
        Working with text
    Interactive navigation
        Navigation Keyboard Shortcuts
    Working with text
        Text introduction
        Basic text commands
        Text properties and layout
        Writing mathematical expressions
        Text rendering With LaTeX
        Annotating text
    Image tutorial
        Startup commands
        Importing image data into Numpy arrays
        Plotting numpy arrays as images
    Customizing Location of Subplot Using GridSpec
        Basic Example of using subplot2grid
        GridSpec and SubplotSpec
        Adjust GridSpec layout
        GridSpec using SubplotSpec
        A Complex Nested GridSpec using SubplotSpec
        GridSpec with Varying Cell Sizes
    Legend guide
        What to be displayed
        Multicolumn Legend
        Legend location
        Multiple Legend
        Legend of Complex Plots
    Annotating Axes
        Annotating with Text with Box
        Annotating with Arrow
        Placing Artist at the anchored location of the Axes
        Using Complex Coordinate with Annotation
        Using ConnectorPatch
        Zoom effect between Axes
        Define Custom BoxStyle
    Our Favorite Recipes
        Sharing axis limits and views
        Easily creating subplots
        Fixing common date annoyances
        Fill Between and Alpha
        Transparent, fancy legends
        Placing text boxes

hi matplotlib developers

as I previously posted, I have thought about structure and flow of the
user guide

my fist cut of a change set is viewable here:
https://github.com/marqh/matplotlib/compare/userGuideShape

it keeps all of the same content as the current user guide but
subdivides some sections into categories:
   configuration
   beginner's guide
   advanced guide

So, all feedback very gratefully received, but a particular focus
requested on:
  - sub-section headings
  - sub-section contents (scope)
  - ordering

I would like to focus on getting the categorisation and ordering
helpful for this piece of work.

I feel that this will give us more accessible ways into adding new
sections or adapting sections but that this should wait for a follow up
activity.

many thanks
mark

···

On Wed, 25 Sep 2013 08:19:59 +0000 mark <markh@...1166...> wrote:

hi matplotlib developers

I have been considering the matplotlib user guide structure and it
has occured to me that there are two user guides interleaved here:
  1. Introduction for new users
  2. Library tour for developers

I think that this structure makes it challenging for new users to
benefit from the user guide as much as they could.

I would like to see the user guide separated into two sections, with
the two different audiences in mind. I feel this would enable new
users of the library to have a more targeted introduction to some of
the neat features without getting bogged down in details they are
unlikely to need (or comprehend).

I am very happy to have a go at this and put up a set of suggested
changes but I would value input from the community on this approach
and my category suggestions before I submit a pull request.

many thanks
mark

------------------------------------------------------------------------------
October Webinars: Code for Performance
Free Intel webinars can help you accelerate application performance.
Explore tips for MPI, OpenMP, advanced profiling, and more. Get the
most from the latest Intel processors and coprocessors. See abstracts
and register >
http://pubads.g.doubleclick.net/gampad/clk?id=60133471&iu=/4140/ostg.clktrk
_______________________________________________ Matplotlib-devel
mailing list Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel

Thank you all for the thoughts so far

I have raised a pull request:
https://github.com/matplotlib/matplotlib/pull/2554

To be clear, this is a 'structure only' pull request, I have made no
documentation changes as yet.

I see this as a part of the process. If we can agree structure we can
work on aspects of the user guide, adding content into appropriate
sections.

all the best
mark

···

On Wed, 25 Sep 2013 08:19:59 +0000 mark <markh@...1166...> wrote:

hi matplotlib developers

I have been considering the matplotlib user guide structure and it
has occured to me that there are two user guides interleaved here:
  1. Introduction for new users
  2. Library tour for developers

I think that this structure makes it challenging for new users to
benefit from the user guide as much as they could.

I would like to see the user guide separated into two sections, with
the two different audiences in mind. I feel this would enable new
users of the library to have a more targeted introduction to some of
the neat features without getting bogged down in details they are
unlikely to need (or comprehend).

I am very happy to have a go at this and put up a set of suggested
changes but I would value input from the community on this approach
and my category suggestions before I submit a pull request.

many thanks
mark

------------------------------------------------------------------------------
October Webinars: Code for Performance
Free Intel webinars can help you accelerate application performance.
Explore tips for MPI, OpenMP, advanced profiling, and more. Get the
most from the latest Intel processors and coprocessors. See abstracts
and register >
http://pubads.g.doubleclick.net/gampad/clk?id=60133471&iu=/4140/ostg.clktrk
_______________________________________________ Matplotlib-devel
mailing list Matplotlib-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/matplotlib-devel