Some writing hints
This is a summary of writing hints. To a certain extent I have written this as a feedback from the exercises and reports from previous years. It may help you both with the exercises and when you write the final report. While I think it contains many useful points, it obviously cannot be considered as a complete set of instructions for creating good explanations and for good writing.Creating good explanations
This is just as important whether you explain something to yourself, if you write a short answer to a question, or if you write a long report.DIFFERENT WAYS TO EXPLAIN
- Text only
- Figure/graph and explanatory
text (always explain a figure!)
- Formula and explanatory text eg. where the meaning of the expression is explained (always do this!)
- Explain a general idea with an example. This is also good to
illustrate a general statement.
- All of these can be used together if necessary. A combination of text, figures, formulas and examples is often the best.
- Itemized lists can be a good tool to highlight several important items. You can use a numbered list if the order is important.
CLARITY AND COMPLETENESS
- A description of a concept or algorithm should be such that the description is complete, i.e. there should be no room for alternatives or other interpretations.
- Especially in a mathematical explanation, definitions, assumptions and other concepts must be clearly and unambiguously defined (what is known and unknown, exactly what do the variables mean, what exactly do the nodes and edges correpond to, what are the reference directions, etc.) This clarity is the most important thing in mathematics, not formatting or mathematical notation.
- An argument in several steps should be complete and without logical gaps. Every step should be explained or at least motivated.
- Often it is good with a top-down approach, where principles and
ideas are explained first before the details. If you need, you can omit
details if there is no ambiguity in how these details can be
reconstructed, or if it is explained later.
- Concepts and notation should be defined before or immediately after they are used.
- Do not introduce unnecessary notation that is not used.
- Hint for finding good explanations: what is the shortest (=simplest) way I can explain this?
- It is worse to say that a false statement is true, than not saying anything at all, or to to say that you believe something is true. Note that this is not a contradiction to the creative exploration that is necessary in problem solving, where a lot of possibilites are tried out as hypotheses (we try them, but do not consider them as true until we have verified this!).
- Errors in mathematical text are expecially bad since the reader
can easily get lost.
- Make sure that the most important parts, concepts etc, are reflected in the overall structure of the explanation and not buried in the text. Try to make sure that the reader can easily distinguish these important parts. Important and/or long equations should get their own line.
- It is important that the reader easily can distinguish facts, discussion, and opinions. You may state beliefs and opinions, but then this must be clearly stated.
- Writing good mathematical explanations is not so easy, and requires a lot of practice and attention to detail.
- You can learn how to explain mathematics from reading a well written mathematical text. Study something that is not too complicated that you liked and considered as well written and easy to understand. However, remember that this explanation will not tell you much about how it was originally found!
Writing a report
CHOOSING THE CONTENT- How to do this depends a lot on the topic, the purpose of the
report and the expected reader(s). This is what ultimately determines
a suitable content.
- It is often good to consider a balance between breadth and depth.
- Make a selection based on what you find important.
- It can be good to find a balance between what you consider important generally, and what you find interesting yourself.
- The most important factor for readability is the structure all the way down to the sentence level.
- Carefully structure the document in chapters, subchapters (only for larger documents), and paragraphs. Do not over-structure in too short parts. Chapters and one subchapter level is sufficient for most purposes. Names of chapters should reflect the content.
- Try to create a modular structure so that the reader always knows what the topic of the current chapter/paragraph/sentence is. Minimize the number of theme changes along the sequential structure of the text, paragraph by paragraph, sentence by sentence.
- Meet the expectation of the reader so that the reader in every step will read what she expects to read. This applies to all structure levels (chapter/paragraph/sentence).
- The readability of a given text can often be improved dramatically only by reshuffling its contents. The chapter/paragraph/sentence structure and the names of chapters may need to be changed along the way as the document develops.
- Let the content determine the stucture and not vice-versa.
- Make sure that the language is good. About this you can probably read elsewhere. Carefully choose the style (formal/informal) so that it fits with the topic and intended audience, and be consistent throughout the document.
- Make sure that the text looks good. Pay attention to details such as spelling, punctuation etc. Actively identify common spelling errors such as "mattematisk", "jämnvikt", errors in writing words together or separately, and other difficulties that you may know you have. A good content can easily be hidden behind a bad or sloppy presentation!
- Use only one paragraph level, where paragraphs are preferably separated by and empty line.
- Use "" only for citations.
- New concepts can be highlighed the first time they are used e.g in italics.
Links and references
- Skrivhjälp på Chalmers
- My notes on how to structure a report. Mainly intended for project reports, master theses and the like.
- Textens hantverk. This book was recommended to me.
- Så skriver du bättre tekniska rapporter
- Svenska skrivregler