Eric Roode - wxPerl Documentation
Title: wxPerl Documentation
Name: Eric J. Roode
Grant Manager: Renée Bäecker
Duration: 3 to 4 months
Started: September, 2009
Write a lot of much-needed documentation for wxPerl.
Benefits to the Perl Community
Perl has a reputation as a language that is not suited for GUI development. This is silly; Perl is as suited for GUI as any other language. But the learning curve for most of Perl's GUI toolkits (with the possible exception of Tk) is steep, and good documentation is sorely needed.
This project will lessen the learning-curve for developing modern GUI applications in Perl, and provide reference materials that even experienced wxPerl programmers can find useful.
A. Overall project deliverables
- A guide to interpreting the wxWidgets API guide (which is oriented toward C++ programmers) for Perl programmers.
- A document listing which wxWidget classes are part of wxPerl, and which ones aren't.
- Create screenshots for all Perl-supported wxWidgets, so users can have more of an idea what each widget is.
- Create a step-by-step walkthrough for installing wxWidgets and wxPerl on as many platforms as possible.
- Convert all wxWidget API docs (oriented toward C++ programmers) to Perl-oriented documents
- Review existing tutorials (listed at http://wxperl.sourceforge.net/documentation.html): Ensure that they work with modern perls and modern wxWidget toolkits; ask authors whether the tutorials could be posted to the wxPerl wiki (with updates as necessary).
B. Phase 1 (2009 Q3) deliverables
- 100% of item 1 above.
- 100% of item 2 above.
- 80 screenshots of various Wx widgets, plus short accompanying demo programs that were used to create each.
- 100% of item 4 above.
- 50 wxWidget class API documents rewritten to describe wxPerl interface instead of wxWidgets interface.
- 0% (yeah, zero) of item 6 above.
- A report to the Perl Foundation detailing how much time was spent on this project during the quarter, and how much of each goal was delivered.
wxPerl is one of the best GUI toolkits for Perl. However, the state of its documentation is poor. My goal is to help to improve it.
This is a huge undertaking, and I expect it to take much longer than just one quarter. So I will detail all the work that needs to be done, and I will list the amount that I think can be accomplished in one quarter. At the end of the quarter, I will assess how much has been accomplished, and will reassess the overall project plan.
There are approximately 600 classes described at http://docs.wxwidgets.org/2.8.4/wx_contents.html, which is the only class documentation referenced from the project documentation page http://wxperl.sourceforge.net/documentation.html. This documentation is designed for C++ progammers, not Perl programmers. For example, there are frequent references to reference parameters, const arguments, and C++ data types. It is not always clear how these should be used in wxPerl.
Of those 600 classes, it is not clear which ones are part of the wxPerl package. All that are should be rewritten to reflect Perl usage instead of C++ usage. Also, they should all include screenshots, so a user can see what each control looks like in action.
There are five tutorials linked on that same documentation page. One was last updated in 2004; the others were written in 2001. It should be verified that they all work with recent perl and wxWidget releases. Probably they should all be reposted to the wxPerl wiki.
I am honestly not sure whether the Phase 1 deliverables that I describe above can all be delivered in 2009 Q3. But that is my best initial estimate, given my time commitment (I pledge to commit 5-10 hours per week to this project for the duration). At the end of the quarter, I will reassess progress and goals, and plan the next phase.
I have been in communication with the wxPerl-users mailing list, asking for ideas and support about this project, and have received encouragement and ideas from notable people on that list. You can review the thread here: http://www.nntp.perl.org/group/perl.wxperl.users/2009/07/msg6524.html
- Reinstall wxPerl on at least two of my systems, documenting each step as I go.
- Write up the installation process as a step-by-step walkthrough for others to follow in my footsteps. Post these guides to the wxPerl wiki.
- Sketch out which wxWidget classes are part of wxPerl, and report my findings to the wxPerl-users mailing list for feedback. Try to get a feel for which are the most "important" classes -- that is, which should be documented first.
- Write a nice document about which classes are/aren't included; post this to the wxPerl wiki.
- Review the wxDemo program that comes with wxPerl. Compare actual usage of classes to the (C++ oriented) wxWidget documentation. Sketch out a "translation guide". Look for exceptions -- things that the C++ documentation would make you think are done one way, but are done differently in wxPerl.
- Write up the results of item 5 as a guide for users.
- Begin writing short programs that each demonstrate one widget (probably borrowing from wxDemo). Take a screenshot of each. Post screenshots, and the demo program that generated each, to the wxPerl wiki.
- Do lots and lots and lots more of item 7, probably in small batches of 5 or 10. As each batch is completed, send them to the wxPerl project and to the wxPerl wiki.
- For a break now and then, review the existing tutorials described above. Duplicate them on my systems. Run them -- do they work? Critique them for style -- do they work under 'use strict'? Other "modern perl"-isms?
- Begin rewriting the wxWidget (C++ oriented) class documentation to be wxPerl-oriented.
- Do lots and lots and lots more of item 10. Some of this can probably be at least partially automated, but I'll still need to check over each one by hand. It probably makes sense to do this in small batches of 5 or 10 at a time. As each batch is completed, send them to the wxPerl project and to the wxPerl wiki.
The project as a whole will take much longer than a quarter; it may go a year or longer. I think that breaking it up into quarter-sized chunks makes sense. It gives some concrete, short-term benefit to the Perl GUI community, and also gives the opportunity to reassess and re-plan in a few months.
My name is Eric J. Roode. I have been a Perl programmer since about 1995, on a variety of platforms (unix, linux, solaris, windows). I am the author of the Readonly, Time::Format, Time::Normalize, Text::Printf, Regexp::Common::time, and other modules. Not all of those are particularly monumentous contributions to the Perl community, but you can look at the documentation I distributed with each of them to get an idea of the quality of my work as a documentor.