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 https://github.com/enthought/chaco/pull/106#issuecomment-15291151.

[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 https://github.com/enthought/chaco/pull/106#issuecomment-28915503.

[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 https://github.com/enthought/chaco/pull/106#issuecomment-15291151.

[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