Writing text is mostly an exercise in empathy. The majority of the content isn't describing an objective reality - the few definitions and theorems do this. Our job is to help ourselves as humans to have an understanding of the mathematical rigour and enhance our ability of working with these concepts.
The usual pirate code interpretation applies, the following are not hard and fast rules, merely guidelines which can be useful. These guidelines are open for improvement, as much as any of the other text.
- Respect readers' cognitive capacity (i.e. brain power). When a reader starts reading, they begin with a certain amount of limited brain power and when they run out, they stop learning.
- Cognitive capacity is depleted faster by complex sentences, having to learn more than one concept at a time, and abstract examples that don't directly relate to a user's work.
- Cognitive capacity is depleted more slowly when we help them feel consistently smart, powerful, and curious. Breaking things down into digestible pieces and minding the flow of the document can help keep them in this state.
- Always try to see from the readers's perspective. When we understand something thoroughly, it becomes obvious to us. This is called the curse of knowledge. In order to write good mathematical text, try to remember what you first needed to know when learning this concept. What jargon did you need to learn? What did you misunderstand? What took a long time to really grasp? Good text meets the reader where they are. It can be helpful to practice explaining the concept to people in person before.
- Describe the problem first, then the solution. Before showing how a definition/theorem/technique works, it's important to explain why it exists. Otherwise, readers won't have the context to know if this information is important to them (is it a relevant problem?) or what prior knowledge/experience to connect it to.
- While writing, don't be afraid to ask questions, especially if you're afraid they might be "dumb". Being vulnerable is hard, but it's the only way for us to more fully understand what we need to explain.
- Help ourselves and other readers to feel smart, powerful, and curious, then maintain this state so that they maintain the motivation and cognitive capacity to keep learning more.
- On some occasions the course notes are meant to be read sequentially, so sometimes it is helpful if they are ordered from the highest to lowest power/effort ratio. Alternatively they can gently introduce and then expand on any given topic.
- On other occasions the course notes will be used as a reference text and therefore, whenever possible, give it a structure so that key concepts can easily be extracted with minimal searching. Currently one element of this is that they key definitions and theorems are highlighted to easily stand out from the other text whilst remaining with the appropriate context.
- Many resources exist and greatly support the understanding of the course material. Useful resources should be linked in a way that it is clear to the reader the purpose of the given resource.
- Headings should help to divide the text into digestible pieces and help to make the text more relatable. Too many subdivisions and then we are lost if we try to get an overview and two few then the heading tells us nothing about the content. It is often comfortable if each part subdivides into between 4 and 7 subparts.
- As humans we enjoy having "characters" to relate to and get familiar with. Even if the character is the Jacobian matrix, for example, it is positive to see this as a character which we will get to know well and understand that behaviour of in various settings.
- Graphics can help concepts to be more relatable, more memorable, more intuitive. However graphics must be simple and avoid being confusing.
- When you assume knowledge, declare it and link to resources for less common knowledge than you're expecting.
- Introduce only one new concept at a time whenever possible (including both text and code examples). Even if many people are able to understand when you introduce more than one, there are also many who will become lost - and even those who don't become lost will have depleted more of their cognitive capacity. Often a definition can be given for a simple setting and then it is easy for the reader to understand how to extend it to the general case whereas when hit with the definition in full generality from the beginning then it is hard to see anything.
- Show, don't tell. It's generally preferable to blend these more naturally into the main text, e.g., by introducing examples to demonstrate an edge case.
- Avoid appeals to authority (e.g., "you should do X, because that's a best practice"). Instead, demonstrate with examples the specific human or mathematical problems caused and/or solved by a particular approach.
- Never assume a more advanced context than you have to.
- In most cases, prefer links between sections of the docs over repeating the same content in multiple sections. Some repetition in content is unavoidable and even essential for learning. However, too much repetition also makes the text more overly verbose.
- Relatable is better than obscure. E.g., a simple and understandable example to illustrate a general theorem can be easily understood and remembered.
- Be emotionally relevant. Explanations and examples that relate to something people have experience with and care about will always be more effective.
- Always prefer simpler, plainer language over complex or jargony language.
- Avoid language that invalidates struggle, such as "easy", "just", "obviously", etc.
- Text is finished when everything that can be removed has been removed, not when everything that could be added is added.
- The text is never finished, it is just improved and ready for the next evolution.
- A large amount of the above text was inspired by the Vue Docs Writing Guide.
- Words To Avoid in Educational Writing.
- On Writing Well (see popular quotes)
- Bird by Bird (see popular quotes)
- Cognitive Load Theory