Difference between revisions of "Authoring Best Practices"

From WeBWorK_wiki
Jump to navigation Jump to search
(Initial commit)
 
 
(5 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
== Perl Code ==
  
== Perl Code ==
−
In the future any problems submitted to the OPL will need to have `perltidy` applied to them.
 +
In the future any problems submitted to the OPL will need to have <code>perltidy</code> applied to them.
  +
  +
== 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.
  +
* If necessary set an appropriate tolerance for answers.
  +
* 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.
   
 
== Macros ==
  
== Macros ==
Line 14: Line 14:
   
 
== MathObjects and PGML ==
  
== MathObjects and PGML ==
−
* Any newly authored problem should use MathObjects and PGML
 +
* Any newly authored problem should use [[Introduction to MathObjects|MathObjects]] and [[Introduction to PGML|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 <code>parserPopUp.pl</code>, <code>parserRadioButtons.pl</code>, <code>parserCheckboxList.pl</code> or <code>parserRadioMultiAnswer.pl</code>.
  +
*
  +
  +
== Obsolete Techniques ==
  +
  +
* <code>beginproblem</code> should be removed from all problems, as it no longer performs any function.
  +
 
{| class="wikitable"
  
{| class="wikitable"
 
|-
  
|-
 
! Obsolete Technique !! Current Technique
  
! Obsolete Technique !! Current Technique
 
|-
  
|-
−
| style="background-color:pink;"| Old answer checkers (e.g. `num_cmp`, `fun_cmp`, `str_cmp` || style="background-color:lightgreen;"| MathObjects answer checkers
 +
| style="background-color:pink;"| Old answer checkers (e.g. <code>num_cmp</code>, <code>fun_cmp</code>, <code>str_cmp</code>) || style="background-color:lightgreen;"| [[Introduction_to_MathObjects#MathObject_Answer_Checkers|MathObjects answer checkers]]
 
|-
  
|-
−
| style="background-color:pink;"| `BEGIN_TEXT`/`END_TEXT` || style="background-color:lightgreen;"| `BEGIN_PGML`/`END_PGML`
 +
| style="background-color:pink;"| Old text processing (e.g. <code>BEGIN_TEXT</code>/<code>END_TEXT</code>, <code>BEGIN_SOLUTION</code>/<code>END_SOLUTION</code>, <code>BEGIN_HINT</code>/<code>END_HINT</code>) || style="background-color:lightgreen;"| [[Introduction to PGML|PGML]]: <code>BEGIN_PGML</code>/<code>END_PGML</code>, <code>BEGIN_PGML_SOLUTION</code>/<code>END_PGML_SOLUTION</code>, <code>BEGIN_PGML_HINT</code>/<code>END_PGML_HINT</code>
 
|}
  
|}
   

Latest revision as of 16:54, 20 January 2025

Perl Code

In the future any problems submitted to the OPL will need to have perltidy applied to them.

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.
  • If necessary set an appropriate tolerance for answers.
  • 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.

Macros

  • Within the problem loadmacros should only be called once, with all of the necessary macros listed one per line.
  • 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

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 parserPopUp.pl, parserRadioButtons.pl, parserCheckboxList.pl or parserRadioMultiAnswer.pl.

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
Retrieved from "https://webwork.maa.org/mediawiki_new/index.php?title=Authoring_Best_Practices&oldid=24943"