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 (\[...\]) only when necessary and appropriate.

In most cases, numerical answers should be coded as MathObject Formulas e.g. $ans = Formula("$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->reduse 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.