Troubleshooting Grammar Problems

1. Sentence fragments

Make sure each word group you have punctuated as a sentence contains a grammatically complete and independent thought that can stand alone as an acceptable sentence.

Incorrect

Tests of the Shroud of Turin have produced some curious findings. For example, the pollen of forty-eight plants native to Europe and the Middle East.

[2nd sentence = fragment]

Correct

Tests of the Shroud of Turin have produced some curious findings. For example, the cloth contains the pollen of forty-eight plants native to Europe and the Middle East.

2. Faulty parallelism

Be sure you use grammatically equal sentence elements to express two or more matching ideas or items in a series.

Incorrect

The candidate’s goals include winning the election, a national health program, and the educational system.

Correct

The candidate’s goals include winning the election, enacting a national health program, and improving the educational system.

Incorrect

Some critics are not so much opposed to capital punishment as postponing it for so long.

Correct

Some critics are not so much opposed to capital punishment as they are to postponing it for so long.

3. Noun strings

The bulk of government and technical writing uses too many noun strings, or groups of nouns “sandwiched” together. Readability suffers when three words that are ordinarily separate nouns follow in succession.

Noun string: NASA continues to work on the International Space Station astronaut living-quarters module development project.

Correction: NASA is still developing the module that will provide living quarters for the astronauts aboard the International Space Station.

4. Subject-Verb agreement

The subject-verb pair guarantees that the sentence means something. Without this core, a sentence fragments and loses its power to speak. Indeed, a sentence only becomes complete when it contains at least a subject and a verb. Subjects and verbs must also agree with one another. That is, the form of the verb has to match the number of things in the subject. A singular subject takes a singular verb, while a plural subject takes a plural verb.

Incorrect: The two best things about the party was the food and the music.

Correct: The two best things about the party were the food and the music.

5. Misplaced Or Dangling Modifier

A misplaced modifier is a word, phrase, or clause that is improperly separated from the word it modifies or describes. Sentences with this error can sound awkward, ridiculous, or confusing. A dangling modifier is a word or phrase that modifies a word not clearly stated in the sentence.

A run-on sentence occurs when you connect two main clauses with no punctuation.

Incorrect: After finally setting off on the trail, the morning felt more exciting.

Correct: After finally setting off on the trail, he felt the morning was more exciting.

6. Run-On Sentence

Incorrect: She tried to sneak out of the house her mother saw her leaving.

Correct: She tried to sneak out of the house, but her mother saw her leaving.

Incorrect: He ran through the field as fast as he could all the while the rain was soaking him to the bone.

Correct: He ran through the field as fast as he could. All the while rain was soaking him to the bone.

7. Lack Of Parallel Structure

Faulty parallelism occurs when two or more parts of a sentence are similar in meaning but not parallel (or grammatically similar) in form. It often occurs with paired constructions and items in a series.

Incorrect: The key directives of his boss were clear:

• Meet monthly sales quotas.

• Aggressive marketing techniques.

• Reporting in every day.
  
  

Correct: The key directives of his boss were clear:

• Meet monthly sales goals.

• Practice aggressive marketing techniques.

• Report in every day.

8. Split Infinitives

An infinitive is the word “to” with a verb. A split infinitive separates the word “to” and the verb with another word (often an adverb). There are no grammar rules that prohibit split infinitives, but many experts disapprove of them. If the sentence sounds awkward by correcting the split, our rule of thumb is to go with what makes the most sense in the context of your writing and for the ease of reading.

Incorrect: He wanted to gradually improve his strength by increasing his weight.

Correct: He wanted to improve his strength gradually by increasing his weight.

References

• https://www.linkedin.com/learning/grammar-girl-s-quick-and-dirty-tips-for-better-writing

How to create a documentation plan

A documentation plan lays down a blueprint for the whole writing project. As a writer, before you embark on your documentation project, create a proper documentation plan and get it approved by key stakeholders. This will establish your credibility in the event of any crisis. It is important to study the marketing/customer requirements document. Ideally, the requirements document should state clearly the features to be documented, the depth of information to be included in the documentation, and the format (HTML, PDF, Word, etc). The next step should be to study the functional specification.

On the basis of MRD and the functional specs, the documentation plan should include the following details:

• The product name, scope, and purpose

• Milestone dates

• List of documents that will be created and/or updated. If the project is about updating an existing product, list the features to be documented. If the project is about releasing a new product, additional planning is required. There can be multiple deliverable types needed, ranging from a single-paged addendum to a context-sensitive online help system.

• Version control tool for managing the source files, for example, Snapshot CM, Rational ClearCase, git.

• Features that will be documented

• Work estimate and committed schedule for documenting each feature or completing each document

• Committed documentation milestones

• Documentation Reviewers including review schedule. There are 2 ways to conduct a review, collect edits individually from each reviewer or hold a review meeting to review everyone’s comments. Multiple reviews may be required. You can also use Adobe’s Shared review process to collect feedback from multiple reviewers.

• Depending on the program include any training material needed for the launch.

• Risks, assumptions, and dependencies. Include the following: Main risks of the documentation project (e.g. last-minute feature additions), probability of each risk, Impact of each risk, Risk mitigation plan, and Owner of the mitigation plan)

• Doc approval process and approvers

• Documentation delivery and distribution plan.

Main components 

• COVER PAGE summarizing the name of the project; organization, and copyright or confidentiality statements.

• Table of Contents – Proposed chapters and their tentative content.

• An introduction that covers the purpose and scope of the plan.

• HISTORY (or REVISION LOG) showing the revisions the plan went through, with dates, the names, and titles of the persons who wrote different versions.

• RISK FACTORS – What are the dependencies to complete the documentation? Which critical factors may bring this project to a halt? What are the impact (H/M/L) and the probability (H/M/L)? What measures should be taken for such an eventuality and who are the mitigation owners.

• Reviewers and Review Process displays the names, titles, and contact information of the writer and all stakeholders involved with the documentation project.

• Product features – what are the features that will be documented.

• Document specs – Is this going to be an online document, a printed document, or both? Will it be single-sourced? Will the project be using a client template? Which version control tool will be used for managing the documentation source files.

• Schedule – What are the milestones in the development of the document? What is the effort required? When should the review cycle(s) be finished? How many rounds of reviews should be allowed? What is the start/end date for the whole project?

Kickstart every technical writing project with a well-crafted and approved plan.