PG author training manual
the information has been moved to
http://webwork.maa.org/wiki/TrainingAuthors/>
Author Training Docs
Training Coders For a Textbook Publishing Project
Sam Hathaway
Preparation
I recently had the task of training and supervising PG coders for a textbook publisher. Coders were Mathematics grad students selected by the publisher. None had experience with WW, but all had some previous programming experience. At least one coder had Perl experience.
I began by creating an authoring wiki on which to post documentation and coordinate the process. I find wikis to be an efficient way to get information up quickly -- I don't have to worry about formatting much, and access control is easy to accomplish. I first posted some suggested reading:
- An introduction to Perl, the perlintro man page. This gives a good introduction to most of the perl features that are used by WeBWorK. There is little reason to delve into further perl documentation.
- A day in the life of a WeBWorK2 professor, a fairly up-to-date walkthrough of instructor functions of WeBWorK, including editing an existing problem. This is not ideal, however, since it spends a lot of time on scoring, assigning, and so on, and very little time on editing. Also, it doesn't cover creating problems from scratch. We should write a document that focuses on using the WeBWorK UI to edit problems -- basically, how to use PGProblemEditor.
- PG language documentation, on the UR WeBWorK site. This documentation is somewhat useful, but it demonstrates a lot of out-of-date practices and is often out-of-date. It doesn't cover MathObjects at all. Useful portions:
- The tutorial consists of example PG problems with comments. These examples could be modernized (for example, using MathObjects where appropriate) and the documentation could be improved. I'd like to see a side-by-side presentation of the source where an explanation of each line/section would be given to the right.
- The explanation of problem text is pretty informative, but most of that information is also available in the PGbasicmacros.pl POD (under EV3).
- Much of the PG language reference documentation (managing answers, the answer hash, pg environment variables, etc.) should probably be merged into the macro file POD.
- The macro file POD documents are useful, but only to the extent that the POD docs are complete. Many are not. This should be fixed so that all macro files are documented with a description and examples at the top and then per-macro docs further down. Much of the standard perl module documentation follows this form and it works well because it caters to both those who need an overhead view or a tutorial and to those who need the details of a particular macro.
I also asked the coders to read up on MathObjects, and directed them to the MathObjects documentation in webwork2/doc/parser, which is available on our development server. (These docs should be expanded, POD-ized, and included with the rest of the PG docs.)
I also gave them a quick overview of problem tagging for the national problem library. I pointed them to the Tagging Problems page at ASU and gave them this template for tagging their own problems.
Finally, I provided an extensively documented example problem. There should be a whole lot more of these. (See comments on the tutorial docs above.)
Since the documentation on interacting with the WeBWorK UI was so poor, I met with the coders via a screen-sharing/teleconferencing system to take them through the process of creating a new problem, editing that problem, previewing with various seeds, saving, and so on.