Style Guide

Discussion: https://github.com/TeamBasedInquiryLearning/library/discussions/63

---

Follow these style suggestions while authoring all materials for the TBIL Resource Library.

• In a <definition>, be sure to enclose the term being defined in a <term> tag.
• To add instructor notes, use the following :

<commentary component="instructor">
<paragraphs>
   <title>Instructor Note</title>
   <p> Using format rat aligns the columns nicely and actually converts decimals to fractions, when applicable.</p>
</paragraphs>
</commentary>

• In an <activity> that uses <task>s, be sure to include the content of the <task> in a <statement>. This ensures that if an <answer> is provided (for an instructor version) that it behaves properly.
• In an <answer>, use the following format:
  • Write letter of answer choice if multiple choice. Write out answer if not multiple choice.
  • If needed, write rationale for the distractors or facilitation notes in a new paragraph.

<answer>
  <p>Letter or answer</p>
  <p>Rationale</p>
</answer>

• If you want to use a table within an <answer> or something else that only appears in the instructor version, use a bare <tabular> without a <table> to prevent it from being numbered. Otherwise in the student version, the numbers will appear to jump.
• You can also use a bare <tabular> in an activity to prevent the table from being numbered. Probably the only reason you would want it numbered is so you can reference it elsewhere.

Math typesetting

• For numbers with four or more digits, use {,} to obtain comma separators without unneeded whitespace: e.g. $1{,}000$ rather than $1,000$.
• We generally prefer to use \dfrac rather than \frac, except possibly when doing a complex fraction like $\frac{1}{x+\frac{1}{x}}$, or when the fraction is in a subscript or superscript such as $7^{\frac{1}{2}}$

Images (including graphs)

• Every <image> (which necessarily includes every graph) needs a <description>. Note that if your description is multiple lines it needs <p> tags. You may use <m> and some other tags in descriptions, see the documentation for additional details.
• Graphs should be produced with a <sageplot>, whenever possible. Note that this is likely to change in the future -- a new method of generating graphs (using PreFigure) will provide more accessibility benefits.
• It is also best practice to write the <sageplot> (or other image generating code) in a separate file, and include it into the text (this will allow you to use characters like <, >, and & without escaping).

Interactives

• Interactives should be done using Doenet, or for 3D interactives use Sageplots.
• Every <interactive> needs a <description>

SageMath Code

• Wherever possible, use syntax that parses as valid Python, to be kind to Python syntax highlighters. E.g. use [1,2,3,4,5] in place of [1..5].