STARMAST style guide
Introduction
Aims
The aim of this project is to produce accessible online resources for incoming students to the School of Mathematics and Statistics. There are two ways that accessibility can be defined in this context:
technical accessibility: ensuring that the way that material is presented is accessible to any user. These include things like ability to screen-read, ability to zoom, correct colour contrasts, etc.
accessibility of language: ensuring that the material itself is understandable by all who read it. This could include users with specific learning difficulties (such as dyslexia or attention deficit disorder) or low literacy skills, international readers where English is not their first language, or even younger people looking for more mathematical support.
Of these, the fact that you are writing in a language that can output to both HTML and Word documents satisfy the somewhat more stringent technical accessibility requirements (such as screen reading, ability to zoom). In addition, the setup for this project (html settings, a LaTeX document class, docx setup) takes care of some other aesthetic changes such as margins, headings, and line-spacing.
The other requirements are up to the writer – you!
Below are some guidelines to follow when writing for STARMAST.
Five main principles
When writing for students using these materials, it’s important to know that these students could be coming from any level of mathematical knowledge or any level of literal knowledge. In particular, your reader can have any level of confidence in their ability to do mathematics or statistics.
The way that you write can directly affect this confidence. Below are five main principles of writing materials for this project.
It’s you, not we.
Traditionally, mathematical writing has used the first-person plural ‘we’, intending to lead the reader on a journey through the material. This is all well and good if you assume that the reader is confident with the work; but what if they are not confident in their ability?
If introductory material is written in an exclusive manner, then a student with absolutely no confidence will struggle. Every student needs to feel included and inspired when reading about mathematics or statistics; so write inclusively and in the active voice.
The problem is that ‘we’ could be inclusive (including the reader) or exclusive (not including the reader). If this is married to concepts which are quite difficult, it can be quick to feel excluded; not part of the journey. In addition, using ‘we’ can be passive – if you want your reader to do mathematics, saying ‘we see this’ and ‘we deduce that’ may create a false sense of security.
Therefore, the writing for this project will use the second-person singular ‘you’, with an emphasis on the active voice. Saying ‘you can do this’ rather than ‘we can see that’ helps to instill confidence in the reader, and actually shifts the focus to the reader doing mathematics.
Nothing is easy.
Your experiences with mathematics are unique, and will not be generally applicable to all students reading your work. If you think that something is ‘easy’ or ‘obvious’, then good for you; but even mentioning this in your writing will crush the confidence of any student reading your work.
So nothing is easy. Not even things you learned in high school. Everyone has to start somewhere, and that somewhere might be here. A consequence of this is that nothing should be hard either; present your material objectively.
Below is a table of banned adjectives, which does not claim to be complete. You can change most of these into adverbs by adding ‘ly’ to the end; these adverbs are banned too.
| Don’t use these. Ever. | |||
|---|---|---|---|
| Easy | Obvious | Trivial | Straightforward |
| Simple | Effortless | Painless | Not hard |
| Foolproof | Elementary | Basic | Clear. |
| Run-of-the-mill | Unchallenging | No trouble | Just |
Please feel free to let tdhc know if you want to make any addition to the list.
Minimise jargon.
If a difficult concept is explained behind jargon or symbols that the student has to look up while trying to understand, then that concept becomes far harder to master. Learning mathematics is hard enough without students trying to translate what is going on.
However, at some point, students will need to be introduced to mathematical terminology. It is a language after all. It is too much to expect to eliminate mathematical or statistical terms entirely, so minimise jargon where you can, and provide references to terms if needed. This includes symbols including the therefore symbol, quantifier symbols, the implied sign, etc; these are often substituted in place for explanation, and learning resources without explanation aren’t good learning resources.
Keep it simple.
Which is easier to read or understand: ‘so’, or ‘whenceforth’? How about: ‘deduction’ or ‘working’?
Again, there may be significant linguistic barriers to understanding; barriers which should not be in place when trying to learn mathematics. Therefore, keep your writing as simple as possible.
Exceptions of course should be made for mathematical terms, which should be clearly defined.
Avoid context.
While it may be tempting to relate everything you write to your education (‘saw this in A-level/Higher’, ‘this was in MT2XXX’, ‘this is used in physics’), please avoid this in your general mathematical writing. So avoid context where possible.
In general, subject-specific examples are to be avoided. Remember that your reader could be of any background; so including (say) a physics problem may put readers off who have absolutely no knowledge of physics.
There are some exceptions; when motivating the subject at hand, you may want to say ‘this is used in X and Y and Z’. This is absolutely fine.
Study guide style
Guide to structure
Each study guide should have:
a summary: two to three lines about the material in the study guide.
(optional) a paragraph of presumed knowledge: relating any presumed knowledge to the contents of the guide.
a paragraph-long introduction to the topic: this could include motivation, historical background, and other topics.
the guide itself: definitions, examples, results. Justification for the results should not be included in the main study guide, and instead be included in an optional proof sheet.
a quick check: two or three introductory questions with multiple choice/fill-in-the-blanks to reinforce knowledge. (Machinery provided by webexercises 1.1.0)
a link to the questions, and (optionally) a list of guides for further reading
a version history and licensing information.
Of these, focus on number 4 first. The summary, presumed knowledge, and introduction should be written at the very end.
Content
Definitions and results need not be numbered; there should only be two or three of these in the study guide. You should however give them names (such as the subject of the definition)
Examples should be numbered, since there are more of these than definitions and results.
There are five environments (called callout blocks) to use; one for definitions and results, one for examples and proofs, one for warnings, one for important things, and one for a tip.
::: {.callout-note}
## Definition of property x
<!-- Always include a title using the above ## syntax. -->
Definition content, where **property x** is bolded.
:::Definition content, where property x is bolded.
::: {.callout-note appearance="simple"}
## Example 1
<!-- Don't forget to enumerate the example. -->
<!-- You will have to do this manually. -->
Example content here, with maths $e^{i\theta}$ and
$$e^{i\theta} = \cos(\theta)+i\sin(\theta).$$
:::Example content here, with maths \(e^{i\theta}\) and
\[e^{i\theta} = \cos(\theta)+i\sin(\theta).\]
::: {.callout-warning}
Be careful with your writing.
:::Be careful with your writing.
::: {.callout-important}
Be really careful with your writing! Oh, and don't divide by $0$.
:::Be really careful with your writing! Oh, and don’t divide by \(0\).
::: {.callout-tip}
Here's what you can do to help your writing.
:::Here’s what you can do to help your writing.
Quick check questions
Refer to the webexercises.qmd document for the machinery used
Aim for two or three questions. You will need to write a version for .html (which uses the webexercises.qmd machinery) and a version for .pdf and .docx (which cannot handle the webexercises). They should be almost exactly the same.
These questions should not be too difficult, instead giving a quick way for students to check understanding before they attempt the question sheet. Depending on the subject at hand, a student should not need a pen and paper to do these questions
Questions and answers style
Guide to structure
Questions
Each question set should have:
A summary: one line about the material in the questions.
A paragraph of presumed knowledge: relating any presumed knowledge to the contents of the guide. A link to the study guide should always be included.
The questions themselves: aim for lots.
A link to the answers at the bottom.
Answers
Each answer set should have:
A summary: one line about the material in the questions.
A paragraph of presumed knowledge: relating any presumed knowledge to the contents of the guide. A link to the questions should always be included.
The answers themselves: only minimal explanation is needed, if any.
Content
Aim for quantity with questions. The idea is that students should have enough to practice on.
Cover all examples in the study guide. The idea is to reinforce knowledge, and the examples are good sources of technique.
General formatting
Writing
Avoid italics and underlining; emphasize using bold text only.
Be careful with the phrase ‘the same method’. If your method differs by even a little, it will not be the same method. Consider using ‘a similar method’ instead.
Don’t start sentences with mathematical symbols.
Don’t use contractions in your writing. These are formal pieces of work.
Avoid ‘maths comma maths’; otherwise the comma looks like part of the maths!
English
For consistency, please use -ize rather than -ise
No Latin phrases please (includes i.e. and e.g.)
Title should be avoided; so write titles like you would write sentences.
Maths
Arguments of functions should be in brackets; so \(\cos(x)\) instead of \(\cos x\).
Use \(\ln\) for the natural logarithm.
Use \(\cos^{-1}(x)\) for inverse cosine, and not \(\arccos\). (Similar for all the trig functions.)
No mixed fractions.
No implied signs.
Do not use \(\times\) for times; using brackets or \(\cdot\).
Other
Always include a further reading and version history segment at end of each guide.
Resources
Inspiration station
Question words
Question words
Prove that…
Verify that…
Evaluate…
Show that…
Calculate…
Find…
Exhibit…
Describe…
Sketch…
Compute…
Deduce…
Calculate…
Explain…
Justify…
Conclude…
Is this true? Or false?
Using X or otherwise…
Define…
State…
Version history
v1.0: initial version created 05/23 by tdhc.
- v1.1: edited 06/24 by tdhc.