From Hdwiki
StyleGuide:Grammar
Contents |
Intro
Grammar is very critical in documentation. Bad grammar will tarnish the credibility of the document. Inconsistent grammar also makes the documentation sound like it was written by a committee, which can also diminish the quality of work. If you are not comfortable or familiar with grammar, you can use Microsoft Word, which has a very good grammar checker. In Microsoft Word, go to Tools, Spelling and Grammar… Then, select the Check grammar box.
Jargon
"Jargon is special vocabulary of a trade or profession," according to the St. Martin’s Handbook. When you are writing for the general public, you want to avoid using terminology that they will not understand. You want to make sure that you define technical terms and verbiage that is specific to Concordia University. If you plan on using specific acronyms throughout a document (to save space), make sure that you spell out the meaning the first time you use it, and then put the acronym in parenthesis.
Example
Bad – The Bears QB, who works at the Help Desk, went to the SCS office to check out their wiki.
Good – The quarterback for the Concordia Golden Bears, who also works for the Information & Technology Department’s Help Desk, went to the School of Continued Studies’ (SCS) office to look at their wiki, which is a collaborative web page.
Passive Voice
Passive voice, according to the St. Martin’s Handbook, "is when the subject is being acted upon." As stated in the handbook, "a passive-voice sentence is formed when the verb “be” is followed by a past participle." For example, the previous sentence is in passive voice (“A passive-voice sentence is formed…”)
Passive voice can be OK if you want to emphasize the “what” rather than the “who”. The reason why you do not want to overuse passive voice is that sentences start to become hard to understand. Instead, you want to use active voice and/or past tense (eliminating the “be” verb).
Example
Bad – The Discussion Boards are used in WebCT when you want to learn asynchronously.
Good – WebCT uses Discussion Boards for asynchronous learning.
Tenses
When composing documentation, you should write in present tense. The reason is that people following directions will be performing actions the same time that they will be reading instructions - in the present. It is OK to use past and future tense if you are dealing with the history or future of the topic. However, avoid these tenses and their variations when you are composing instructions and commands.
Example
Bad – To check grammar, you will use Microsoft Word.
Bad – To check grammar, you used Microsoft Word.
Bad – To check grammar, you will have used Microsoft Word.
Bad – To check grammar, you would have had used Microsoft Word.
Good – To check grammar, use Microsoft Word.
