Please refer to the site-wide style guide (the previous page in these help documents) for general guidelines. The rest of this document is specific to grammar points.
General guidelines
Grammar content is to serve both teachers and students.
- Write clearly and concisely.
- Keep the language simple and accessible to the non-native reader.
- Use examples to illustrate a point.
- Explanations should make sense to the non-native reader (avoid 'teacher logic', i.e. explanations that make sense if you already know the answer*).
- Avoid technical or higher-level vocabulary.
- Use bullet points for lists.
Content
Single grammar points should cover a single aspect of a grammar pattern. They should be as "granular" as possible—namely, they should be one thing in terms of meaning. Different aspects of the usage of a single word/pattern (for example, "will" meaning prediction versus a decision made at the time of speaking) should be written up as separate points. Comparative grammar points can then be used to discuss the differences in usage and meaning.
It is recommended that in approaching grammar, you start with the 'big' ideas first and build on those to be more specific in subsequent points.
Specific instances of vocabulary used in grammar patterns (for example, different verbs followed by gerunds and infinitives and their meanings) will be addressed in an as yet to be determined way by the system.
Titles
When writing a title, highlight key points with the use of all caps (for technical reasons & clean URLS, other punctuation, such as quote marks, is best not used).
Keep titles as brief and descriptive as possible.
Single grammar points
The following applies to sections in single grammar points.
Structure
The structure section is where you lay out the pattern in question, and highlight the language structure and parts of speech used by that structure (in general terms) using the "Styles" dropdown on the toolbar (as covered in the site-wide style guide).
Example
The example should use the same highlighting as the structure to draw attention to the features of the grammar.
Thereafter, when drawing attention to the language structure, make judicious use of the colour highlighting. If things are looking crazy, please use bold and not the highlighting to draw attention to the structure.
Meaning
Keep this as short as you can. It should focus on meaning, not function wherever possible.
Rather than "To replace clauses of reason or cause", "To give a reason or cause" is preferable.
Description
Here you can get into the weeds. Make as much use of examples and explanation as you need to clarify the meaning and use of the grammar point.
Dialogue setting
Set up the dialogue that you will use to illustrate the grammar in action. Add notes here to explain motivation and connotation that comes from the use of the grammar that would not be obvious to a student.
Dialogue
Use bold to highlight the structure. Make sure you remember to alternate between speakers A and B (and C and D if required).
Comparative grammar points
At all times, do your best to make the comparison as clear as possible.
Titles
Do not use the word "comparison" or similar language in comparative grammar points (this makes alphabetical lists harder to parse). Use the structure: "POINT A and POINT B" or a more general title such as "Present tenses" or "Conditionals".
Similarities and differences
Make the differences and similarities as clear as you can. Use of a table is recommended. You can use coloured highlighting to make the structures clear.
Please note that when you insert a table, you need to muck around a bit with the settings to get it right. In the above image, the first row is set as the table header. You can do this when inserting the table, or by configuring the table properties after you have set up the table. Just right click your table and you will see the menu shown below (this will also allow you to add or delete columns and rows).
You can then set the first row as the table header.
You can ignore everything else in the above dialogue box as it's all taken care of automatically. Likewise, don't try to style the header yourself with bold etc.
Dialogues
Follow the same guidelines as for a single grammar point. However, in the case of a comparative point, it is more necessary to include notes on usage and difference in meaning.
—
* In a textbook I used years ago, they explained how to talk about hobbies and sports like this:
- Use "play" for games and ball sports as in "play football" and "play chess".
- Use "do" for individual activities as in "do yoga" or "do karate".
- Use "go" for -ing words as in "go surfing" and "go jogging".
The flaw in (3) is that you only know to use "go" if you already know that something uses -ing—chicken and egg. My student called that 'teacher logic'. Surfing and jogging are both individual activities and so students would choose "do". A better rule might have been "Use 'go' for activities where you move or need to go to a place to do it as in 'go surfing' or 'go jogging'." This is often easier said than done!