Difference between revisions of "Authoring Best Practices"
Jump to navigation
Jump to search
(Update perltidy info.) |
(Add stuff) |
||
| Line 3: | Line 3: | ||
* Check your problem with multiple random seeds. |
* Check your problem with multiple random seeds. |
||
* Make sure that the question accepts the correct answer, and doesn't accept incorrect answers. |
* 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. |
+ | * For any formulas, set an appropriate domain to avoid division by zero, very large values and very small numbers (see [https://openwebwork.github.io/pg-docs/pod/pg/doc/MathObjectsAnswerCheckers.html#Tolerances-and-Limits Tolerances and Limits]). |
| − | * If necessary set an appropriate tolerance for answers. |
+ | * If necessary set an appropriate tolerance for answers (see [https://openwebwork.github.io/pg-docs/pod/pg/doc/MathObjectsAnswerCheckers.html#Tolerances-and-Limits 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 <code>Compute()</code> to generate the <code>correct_ans_latex_string</code>, or explicitly set it. |
* Check that the correct answers display in a format that is meaningful to students (e.g. a fraction instead of a decimal). Use <code>Compute()</code> to generate the <code>correct_ans_latex_string</code>, or explicitly set it. |
||
| − | * Check that the hardcopy generates without errors and displays properly. |
+ | * Check that the hardcopy generates without errors and displays properly (using the "Generate Hardcopy" tab at the bottom of the problem editor). |
== Macros == |
== Macros == |
||
| − | * Within the problem |
+ | * Within the problem <code>loadMacros</code> 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. |
* 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. |
* The first macro loaded should be PGstandard.pl, which loads the following macros, so none of them should be explicitly loaded. |
||
| Line 23: | Line 23: | ||
== Style and Pedagogy == |
== 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 |
+ | * If the correct answer is to be chosen from a fixed list of choices, don't use a text box. You can use [https://openwebwork.github.io/pg-docs/sample-problems/Misc/MultipleChoicePopup.html a drop-down menu], [https://openwebwork.github.io/pg-docs/sample-problems/Misc/MultipleChoiceRadio.html radio buttons], [https://openwebwork.github.io/pg-docs/sample-problems/Misc/MultipleChoiceCheckbox.html check boxes]. |
| − | * |
+ | * For cases where the answer may have different forms, you can use [https://openwebwork.github.io/pg-docs/sample-problems/LinearAlgebra/MatrixOperations.html radio multi-answer]. |
== Perl Code == |
== Perl Code == |
||
Revision as of 17:48, 19 June 2025
Contents
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 thecorrect_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).
Macros
- Within the problem
loadMacrosshould 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
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, check boxes.
- For cases where the answer may have different forms, you can use radio multi-answer.
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
beginproblemshould 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
|
