Added FAQ directory under docs, with several entries

[kjmcclaning]

FAQ directory with entries on Chaco line plots, controlling various aspects of plots, the start of a Chaco cheat sheet, and how to add a colorbar to an image plot.

[pberkes]

@kjmcclaning I quite like the cheat sheet and I'd like to move that to the core documentation. On the other hand, I'm not sure that the big printouts of everything inside Chaco classes is very educational, and adds little to the API docs (http://docs.enthought.com/chaco/programmers_reference.html), so I would suggest publishing it on a more suitable medium (a series of blog posts, if you have a blog?)

What do others think?

[kjmcclaning]

I believe that the documentation is the major issue that keeps Chaco
from being more widely used. The examples and tutorials are are
excellent but they are often very confusing.

Speaking as a non-expert user of Chaco, I found that you have to travel
pretty far into the Python forest to answer even simple questions like,
"How do I label the y-axis of a color bar." You can instrospect into the
various instances but you often get different answers depending upon
where precisely you perform the introspection because of the Traits
package's lazy initialization philosophy and because of how Traits uses
metaclasses to build Traited variables. This is very confusing to the
newbie.

The source code at the very beginning of each document is meant to give
the reader a simple, complete, unambiguous, paste-able into Pylab, piece
of code that examines a single aspect of a plot (such as controlling the
title). The introspections in main are meant to display only the
objects that are applicable to the topic at hand (i.e. controlling the
title). I believe this cleanliness will help the wanna-be Chaco user.

I originally removed most of the lines of the introspection output and
included only the items that covered the topic of interest but I found
myself re-running the code when I wanted to answer a different question
so I just decided to leave them all in. Perhaps this was an incorrect
decision but I actually refer to the introspection outputs in the
documentation quite a bit when I'm trying to figure other things out.

The problem I see with including only the cheat sheet is that the cheat
sheet alone lacks a sense of how things fit together and at what point
various items are accessible. For example, a tremendous number of
instances are created and wired together when the user performs a simple
command like

myPlot = Plot( myArrayPlotData )

and expressing what those instances are and how they work together to
produce a plot is a large part of how to use Chaco effectively. The code
and introspections in the documentation are meant to guide the reader
through those connections.

On 3/22/2013 7:02 AM, Pietro Berkes wrote:

@kjmcclaning https://github.com/kjmcclaning I quite like the cheat
sheet and I'd like to move that to the core documentation. On the
other hand, I'm not sure that the big printouts of everything inside
Chaco classes is very educational, and adds little to the API docs
(http://docs.enthought.com/chaco/programmers_reference.html), so I
would suggest publishing it on a more suitable medium (a series of
blog posts, if you have a blog?)

What do others think?

—
Reply to this email directly or view it on GitHub
#106 (comment).

[jonathanrocher]

@kjmcclaning Sorry for the delay in getting back to you.

I agree with Pietro that this content isn't in a form that can be merged as is IMO. There is a ton of valuable code and tips there but I don't think dumping it into a new FAQ folder is the right way forward. There is no question Chaco's documentation isn't where it needs to be and contributions to change this is very welcome. I would like to suggest that we cherry pick examples you are giving that would allow to fill some of the sections of the user manual that are not written in particular in the http://docs.enthought.com/chaco/user_manual/how_do_i.html which has a purpose similar to your FAQ. One obvious thing you could contribute there is how do I customize the y axis of a colorbar? Other aspects of your documentation would make for valuable additions to the programmer's reference (http://docs.enthought.com/chaco/programmers_reference.html). It will take effort to merge things and yet keep the coherence of the whole descriptions.

If you have the time, please cherry pick 1 or 2 files at a time and make a PR for atomic improvements to the user guide and programmer's reference and we can discuss them individually. If you don't have the time, and since I am planning on putting some effort into documentation in the next few months, I would like to have your permission to re-use/adapt some of your code to do these improvements. Let us know how you want to be involved.

Ps In your response to you, diving into the gory details of Traits and CHaco and understanding the mapping of it all is a serious task but it is very difficult to transfer that understanding to someone else, and most of this isn't the goal of the Chaco documentation. I agree with Pietro that some of that understanding process would make for valuable blog posts.

[kjmcclaning]

Jonathan et al. --

Please feel free to re-use/adapt any of the code or other text I
submitted. I've expanded the documentation over the last several months
and will upload that data to github in the next few days.

I would very much enjoy being involved with writing documentation for
Traits and Chaco. However, as a warning, I am not a professional
programmer and have never worked in a collaborative programming
environment. Most of my Python adventures involve solo development of
stand-alone instrument controllers and some minor data processing.

The form of the documentation I submitted arose from my frustration of
having figured out how to do something once, then having to re-figure it
out when I needed to do it again. I would find myself forever traipsing
through the same inheritance trees to find the attribute I needed.

I'll work on your suggestion of "How do I customize the y axis of a
colorbar?" and make a pull request as an atomic improvement.

Kevin

On 11/20/2013 1:34 PM, Jonathan Rocher wrote:

@kjmcclaning https://github.com/kjmcclaning Sorry for the delay in
getting back to you.

I agree with Pietro that this content isn't in a form that can be
merged as is IMO. There is a ton of valuable code and tips there but I
don't think dumping it into a new FAQ folder is the right way forward.
There is no question Chaco's documentation isn't where it needs to be
and contributions to change this is very welcome. I would like to
suggest that we cherry pick examples you are giving that would allow
to fill some of the sections of the user manual that are not written
in particular in the
http://docs.enthought.com/chaco/user_manual/how_do_i.html which has a
purpose similar to your FAQ. One obvious thing you could contribute
there is how do I customize the y axis of a colorbar? Other aspects of
your documentation would make for valuable additions to the
programmer's reference
(http://docs.enthought.com/chaco/programmers_reference.html ). It will
take effort to merge things and yet keep the coherence of the whole
descriptions.

If you have the time, please cherry pick 1 or 2 files at a time and
make a PR for atomic improvements to the user guide and programmer's
reference and we can discuss them individually. If you don't have the
time, and since I am planning on putting some effort into
documentation in the next few months, I would like to have your
permission to re-use/adapt some of your code to do these improvements.
Let us know how you want to be involved.

Ps In your response to you, diving into the gory details of Traits and
CHaco and understanding the mapping of it all is a serious task but it
is very difficult to transfer that understanding to someone else, and
most of this isn't the goal of the Chaco documentation. I agree with
Pietro that some of that understanding process would make for valuable
blog posts.

—
Reply to this email directly or view it on GitHub
#106 (comment).

[kjmcclaning]

All --

I've published most of the Traits, TraitsUI and Chaco documentation that
I wrote on my personal blog at

http://www.mcclaning.com/kevin/index.php/python

Feel free to use as you see fit.

Also, would it be within the rules to post this link to the Enthough-Dev
Digest list?

Kevin

On 3/22/2013 7:02 AM, Pietro Berkes wrote:

@kjmcclaning https://github.com/kjmcclaning I quite like the cheat
sheet and I'd like to move that to the core documentation. On the
other hand, I'm not sure that the big printouts of everything inside
Chaco classes is very educational, and adds little to the API docs
(http://docs.enthought.com/chaco/programmers_reference.html), so I
would suggest publishing it on a more suitable medium (a series of
blog posts, if you have a blog?)

What do others think?

—
Reply to this email directly or view it on GitHub
#106 (comment).

[jdmarch]

@kjmcclaning - Lovely blog posts!! Yes, please feel free to post the link to the Enthought-Dev list (to be clear, the list is not a Digest, though you presumably have elected to receive Digest summaries of the list's postings; see http://www.list.org/mailman-member/node27.html). You would post by sending a new email to [email protected]

I also added a link to your blog here: https://support.enthought.com/entries/22878645-Introductory-materials-for-Traits-and-Traits-UI