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.
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:
Introduction for new users
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 >
Thanks for the interest. I agree there's lots that can be done to improve it.
You may want to familiarize yourself with MEP10 ( Mep10 · matplotlib/matplotlib Wiki · GitHub) 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
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 matplotlib-devel List Signup and Options
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 matplotlib-devel List Signup and Options
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
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:
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 matplotlib-devel List Signup and Options
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 matplotlib-devel List Signup and Options
