Authoring Best Practices

Functionality

• Check your problem with multiple random seeds.
• Make sure that the question accepts the correct answer, and doesn't accept incorrect answers.
• For any formulas, set an appropriate domain to avoid division by zero, very large values and very small numbers (see Tolerances and Limits).
• If necessary set an appropriate tolerance for answers (see Tolerances and Limits).
• Check that the correct answers display in a format that is meaningful to students (e.g. a fraction instead of a decimal). Use Compute() to generate the correct_ans_latex_string, or explicitly set it.
• Check that the hardcopy generates without errors and displays properly (using the "Generate Hardcopy" tab at the bottom of the problem editor).
• A problem should not return an error if a student enters an answer in an acceptable format (e.g. if the question asks for a function, and the correct answer happens to be a constant function, students should not get an error message if they enter a non-constant function).

Macros

• Within the problem loadMacros should only be called once, with all of the necessary macros listed. Macro files will load their dependencies, so you do not need to load them explicitly (e.g. if you load PGML.pl you do not need to load MathObjects.pl).
• Any macros that are not used by the problem should be removed when copying code from another problem.
• The first macro loaded should be PGstandard.pl, which loads the following macros, so none of them should be explicitly loaded.
  • PG.pl
  • PGbasicmacros.pl
  • PGanswermacros.pl
  • PGauxiliaryFunctions.pl
  • customizeLaTeX.pl
• The last macro loaded should be PGcourse.pl.

MathObjects and PGML

• Any newly authored problem should use MathObjects and PGML

• Existing problems can be converted to PGML using the "Convert to PGML" option in the "Format Code" tab of the PG Editor. Note: work may be needed after the conversion to get the problem to run correctly.

Style and Pedagogy

• If the correct answer is to be chosen from a fixed list of choices, don't use a text box. You can use a drop-down menu, radio buttons, or check boxes.
• For cases where the answer may have different forms, you can use radio multi-answer.
• Generic help messages for different types of answers can be added using helpLink.
• Place answer boxes in a way that makes it clear what should be entered in them.
• If you want to include a hint, use the built-in functionality (BEGIN_PGML_HINT/END_PGML_HINT). When using this construction you do not need to include a title on the hint.
• Include a full solution to the problem using BEGIN_PGML_SOLUTION/END_PGML_SOLUTION. WeBWorK will let you choose whether the solution is made available to students.
• Do not include instructions telling students to do something that is not being checked by the problem (e.g. "sketch the graph of the function and use the graph to answer the following questions", "find the derivative using only the definition of derivative").
• There are a number of sample problems that have good authoring techniques applied. They can be accessed at the PG docs home or when authoring, click on the "Sample Problems" link at the top of the PG Editor inside WeBWorK.

Classifying and Describing Problems

• Fill in all of the tags correctly for your problem.
• If there are features of the problem that are not apparent from the text, add a comment to instructors indicating this (e.g. "the matrix always has rank 2", "this problem sometimes generates a system with no solution").

Perl Code

In the future any problems submitted to the OPL will need to be formatted using the standards of the project. As of WeBWorK 2.18 this can be done from the WeBWorK Problem Editor using the "Reformat the code using perltidy" action in the "Format Code" tab. Advanced users can accomplish this using the pg/bin/perltidy-pg.pl script.

Obsolete Techniques

• beginproblem should be removed from all problems, as it no longer performs any function.

Obsolete Technique	Current Technique
Old answer checkers (e.g. num_cmp, fun_cmp, str_cmp)	MathObjects answer checkers
Old text processing (e.g. BEGIN_TEXT/END_TEXT, BEGIN_SOLUTION/END_SOLUTION, BEGIN_HINT/END_HINT)	PGML: BEGIN_PGML/END_PGML, BEGIN_PGML_SOLUTION/END_PGML_SOLUTION, BEGIN_PGML_HINT/END_PGML_HINT