Writing Exercises: Problem Structure

Problem Structure

Problems are a collection of a problem overview (or introduction), a question, and a solution. All problems are contained within an element with a class of "problems".

The basic structure of a problem looks something like this (indents will be appropriate for copy and paste):

                <div class="problems">
                    <div id="problem-type-or-description">
                        <p class="problem"><!-- An overview of the problem including all needed info. --></p>
                        <p class="question"><!-- The question to ask the student. --></p>
                        <p class="solution"><!-- The correct answer expected of the student. --></p>
                    </div>
                </div>

The exact elements that you use aren't important (they could be divs or paragraphs or something else entirely); all that matters is that they have the proper classes ("problem", "question", and "solution").

When defining the various parts of the problem, it will be necessary to refer to the variables you defined in the vars block. When defining the introduction, question, and solution, you can always refer to previously-defined variables with a <var></var> block; for the full list of formatting options (which are all available when defining the introduction and question), see the Formatting section of this wiki.

Note on div class="problems" and p class="problem"

You will see that at the top, we have a <div class="problems"> markup. This is a wrapper which contains all the code that generates the problem - the question, the solution, the hints, multiple types of problems, everything except globally declared variables.

In contrast, the <p class="problem"> markup indicates that you are generating the intro or overview part of the problem. We want to use the class "problem" here for consistency but you can can think of it as "introduction" or "overview" or "needed info."

Problem or Introduction

The problem overview/introduction is optional and is defined with a class of "problem." It is mainly useful for word problems or any kind of problem that has important text or information that isn't explicitly part of the statement of the question. For example, a Physics problem may describe the situation and the various objects in the world before asking about a certain quality of a certain object.

You could also put information in after the question if you want to provide clarity on how to answer the question. For example:

    <p class="question">Express <var>DECIMAL</var> as a fraction.</p>
    <p class="extra-info"><i>(Extra Info: You can express this as any fraction -
      you don't have to "reduce to lowest terms" for the correct answer)</i></p>

will let the user know what kind of answer is acceptable. If you are doing this, extra-info can be used for consistency.

Question

The question is required and is defined with a class of "question". At the moment, the question is appended directly after the problem and is formatted the same, although this may change depending on the system.

We provide these guidelines for how to choose the problem overview content and question content, but they are ultimately left at the discretion of the exercise author. The contents are not handled or interpreted in any particular way.

Solution

Unlike problem introductions and questions, solutions do have a very specific form of markup. Like introductions and questions, it is the class name ("solution") which matters, not the element type; however, the content of the solution element is very important and is used as the basis for validating the user's input.

For example, a valid solution that is dynamically-generated from a previously-created variable would be:

<p class="solution"><var>round(DIST1)</var></p>

The user would then need to enter a number into the fill-in-the-blank form that matches the DIST1 variable, rounded to the nearest integer.

Back to Writing Exercises: Home