Problem Authoring Best Practices

Below is a summary of the stylistic guidelines for "cleaning" and uniformizing WeBWorK problems that were adopted during the WeBWorK Programming Workshop at MSRI on 20-24 May 2004. These guidelines apply to problems intended for the National Problem Library.

The items listed below cover the most common issues. Those who are writing problems for the first time should use National Problem Library problems as templates to insure a good working model.

Guidelines

Answer boxes should be labeled. If a question asks for the derivative of f(x), then "f'(x) = [Answer Box]" is appropriate. If there isn't an obvious label, then "Answer: [Answer Box]" should be used. Also, if the answer implicitly includes units that aren't to be included in the answer box, then they should appear after the box, e.g. "Answer: [Answer Box] furlongs".

All answer boxes should be large enough to actually hold the answer without scrolling. This is easily verified by pasting the correct answer into the box.

Use complete sentences. Check for grammatical and spelling errors. When using words with different singular and plural forms, check the associated number and use the appropriate form rather than e.g. "$n bicycle(s)".

Use display equations e.g.

\[...\]

only when necessary and appropriate.

In most cases, numerical answers should be coded using Compute() e.g. $ans = Compute("$a*cos($b)") instead of $ans = $a*cos($b). This way, if a correct answer is 7*sin(pi/4), when a student checks the "Show Answer" box after the deadline then she will see 7*sin(pi/4) instead of 4.949747468305832. The exception to this rule is when the answer would be extremely complicated/messy, in which case it may be better to use the numerical form.

Use "pi" instead of the number 3.14159... and "e" instead of the number 2.71828... MathObjects recognizes these constants and they will be rendered using the appropriate symbols.

All characters and expressions that would be in math mode in a text or research article should be in math mode in a WeBWorK problem.

Use $f->reduce for all displayed polynomials where there is the potential for coefficients of 0, 1, or -1. This will eliminate the unnecessary 1's and -1's, and will drop terms with a coefficient of 0.

No hints or comments referring to specific texts or other works should be used.

Unnecessary calls to packages in the "loadMacros" portion of a problem should not be used. In particular, "PGbasicmacros.pl", "PGanswermacros.pl", and "PGauxiliaryFunctions.pl" are the only packages that need always be present. "PG.pl" is never needed and "PGchoicemacros.pl" and "PGgraphmacros.pl" are rarely needed.

Use the MathObjects $obj->cmp method to get the appropriate answer evaluators for your answer. Old answer evaluators that have been superseded should not be used.

Style Recommendations

• Don't load a macro unless you actually use it.
• Use descriptive variable names like $xint for an x-intercept (instead of just $x)
• Separate blocks of code using extra space and dividers like

#############################
#  Main text

• Layout the code visually so that it is easily readable by other humans.

This is a long line of text.$PAR It's not so easy to see the paragraph break.

This is a long line of text.
$BR
$BR 
(a) Now it's easy to see the paragraph break!

• Don't use $SPACE$SPACE$SPACE$SPACE to indent.
• Put the info about the textbook, chapter, section, problem number, etc. in the problem tagging section, not inside of a text block BEGIN_TEXT ... END_TEXT.
• Give graphs captions.
• Make graphs big enough in HTML and the PDF hardcopy. Check that the graph's resolution, font size, line thickness, etc. are all readable.
• When using a graph with more than a few lines of text, use the ColumnTable(column 1, column 2, options) routine provided by the macro unionTables.pl to provide a two column format. Put the text in column 1 and the graph in column 2. If you have multiple graphs, use a table of graphs.
• Use left justification most of the time, and center sparingly.
• Make your math formulas readable using \displaystyle:

\( \displaystyle \frac{a}{b} \)
\( \displaystyle \frac{ \displaystyle\frac{a}{b} }{ \displaystyle\frac{c}{d} } \)

• Test your problem in images and jsMath mode. Don't use \dfrac{}{} because jsMath will doesn't understand that command.
• If you were writing a textbook and would put something in TeX, then put it in TeX.
• Make sure the PDF output works and everything is readable and usable.
• Use multiple contexts and text blocks when appropriate
• Don't overuse BOLD, don't use ALL CAPS, and DON'T SHOUT AT YOUR READER!
• For questions with multiple parts, use extra space between parts and keep each part together as a block. This will make it easier to read and use.
• Write comments for other instructors. For example, COMMENT('MathObject version'); or COMMENT('MathObject version. Not randomized.');

Training authors/coders for writing PG problems

2007 document from Sam Hathaway TrainingAuthors