From the free course Writing Guide on Lykke
Grammar, Mechanics, and Documentation Handbook
Key concepts: Grammar and mechanics · Style · Documentation
A comprehensive technical guide to the mechanics of writing, including grammar, style, and proper documentation standards.
Grammar, Mechanics, and Documentation Handbook
The "Handbook" is the underlying specification for effective human-to-human communication in written form. Much like a technical specification or an API documentation, grammar and mechanics provide the protocols that ensure a message sent by a writer is accurately decoded by a reader. In professional and academic contexts, these rules are not merely arbitrary conventions; they are the structural framework that supports complex reasoning, prevents ambiguity, and establishes the writer's credibility (ethos).
Grammar and Mechanics: The Syntax of Thought
Grammar is the system of rules governing the composition of clauses, phrases, and words. Mechanics refers to the technical aspects of writing—punctuation, capitalization, and spelling—that facilitate the visual processing of text. Together, they form the Syntax of the English language.
Sentence Architecture and Control Flow
At its core, an English sentence is a discrete unit of thought consisting of at least one Independent Clause. The architecture of a sentence determines its "control flow"—how the reader's attention is directed through the information.
Definition: Independent Clause A group of words containing a subject and a predicate that expresses a complete thought and can stand alone as a sentence.
Errors in sentence architecture often result in "syntax errors" that halt the reader's processing. The most common are Fragments, Run-on Sentences, and Comma Splices.
| Error Type | Technical Description | Example | Correction Strategy |
|---|---|---|---|
| Fragment | A dependent clause or phrase punctuated as a full sentence; lacks a subject or finite verb. | "Because the server crashed." | Attach to an independent clause or add missing components. |
| Run-on | Two independent clauses joined without any punctuation or coordinating conjunction. | "The data arrived the script failed." | Insert a period, semicolon, or comma + conjunction. |
| Comma Splice | Two independent clauses joined by only a comma. | "The test passed, the deployment began." | Replace comma with a semicolon or add a coordinating conjunction. |
Punctuation as Logical Operators
Punctuation marks function as logical operators within a sentence, defining the relationships between different data points (clauses and phrases).
- The Semicolon (
;): Functions like a "soft period." It connects two closely related independent clauses, signaling that the second clause expands upon or contrasts with the first. - The Colon (
:): Acts as a gateway. It signals that the information following it will define, illustrate, or list what preceded it. - The Comma (
,): The most versatile operator, used for delimiting non-essential information (parenthetical elements), separating items in a list, or joining clauses with a coordinator.
The Art of Style: Optimizing the User Interface
If grammar is the backend logic, Style is the User Interface (UI). Style involves the choices a writer makes regarding word choice (diction), sentence variety, and tone to ensure the message is not only correct but also persuasive and easy to consume.
Clarity and Concision
In technical and academic writing, the goal is to minimize the Cognitive Load on the reader. This is achieved through:
- Active Voice: Ensuring the subject of the sentence performs the action.
- Eliminating Nominalizations: Avoiding the conversion of verbs into clunky nouns (e.g., using "analyze" instead of "conduct an analysis of").
- Reducing Wordiness: Stripping away "filler" phrases that do not add semantic value.
| Feature | Passive Voice (Sub-optimal) | Active Voice (Optimized) |
|---|---|---|
| Structure | Object + "to be" + Past Participle + "by" Subject | Subject + Verb + Object |
| Clarity | Obscures the actor; can be ambiguous. | Clearly identifies the actor. |
| Length | Usually longer (more tokens). | Usually shorter (fewer tokens). |
| Example | "The bug was fixed by the developer." | "The developer fixed the bug." |
Inclusive and Intersectional Rhetoric
Modern style guides emphasize Inclusive Rhetoric. This involves recognizing that language is not neutral; it carries historical and social weight. Intersectional rhetoric considers how overlapping identities (race, gender, class, ability) affect how a reader perceives and is represented by a text.
- Avoid Universalizing: Don't assume a "default" reader (e.g., using "he" as a generic pronoun).
- People-First Language: Focus on the individual rather than a descriptor (e.g., "a person with a disability" vs. "a disabled person"), though this varies by community preference.
- Bias Mitigation: Actively auditing text for exclusionary metaphors or idioms.
Style Linter Logic
We can conceptualize style as a set of heuristic checks performed on a text buffer.
ALGORITHM StyleCheck(Document text):
FOR EACH Sentence IN text:
// Check for Passive Voice
IF Sentence CONTAINS ("am" | "is" | "are" | "was" | "were") + PastParticiple:
FLAG "Passive Voice Detected"
SUGGEST "Convert to Active Voice"
// Check for Nominalization
IF Sentence CONTAINS ("conduct an analysis" | "make a decision"):
FLAG "Nominalization detected"
SUGGEST "Use direct verb (e.g., 'analyze', 'decide')"
// Check for Wordiness
IF Sentence CONTAINS ("due to the fact that"):
FLAG "Wordy phrase"
SUGGEST "Use 'because'"
RETURN Report
Documentation: Dependency Management for Ideas
Documentation is the formal process of citing sources. In the same way that a software project lists its dependencies in a package.json or requirements.txt file, an academic paper uses documentation to acknowledge the "upstream" ideas it relies upon.
Why Documentation Matters
- Academic Integrity: Avoiding plagiarism by giving credit to original authors.
- Provenance and Traceability: Allowing readers to trace an idea back to its source to verify its validity.
- Ethos: Demonstrating that the writer has conducted thorough research and is engaged with the existing scholarly conversation.
Comparison of Documentation Styles
Different disciplines use different "protocols" for documentation, optimized for their specific needs.
| Style | Full Name | Primary Use Case | Citation Logic |
|---|---|---|---|
| MLA | Modern Language Association | Humanities (Literature, Arts) | Focuses on Authorship (Author, Page #). |
| APA | American Psychological Association | Social Sciences, Education | Focuses on Recency (Author, Date). |
| CMS | Chicago Manual of Style | History, Business, Fine Arts | Uses Footnotes/Endnotes for minimal disruption. |
| IEEE | Institute of Electrical and Electronics Engineers | Engineering, Computer Science | Uses Numbered Brackets [1] for efficiency. |
The Metadata of a Citation
A citation is essentially a structured data object. Whether it appears in a bibliography or a reference list, it contains specific fields required for identification.
Working Example: Citing a Source in MLA vs. APA
Consider a source: A book by Ada Lovelace titled The Analytical Engine, published in 1843 by London Press.
- MLA In-text: (Lovelace 42)
- MLA Works Cited: Lovelace, Ada. The Analytical Engine. London Press, 1843.
- APA In-text: (Lovelace, 1843)
- APA References: Lovelace, A. (1843). The Analytical Engine. London Press.
Common Pitfalls and Edge Cases
The "Dangling Modifier" Bug
A dangling modifier occurs when a descriptive phrase is placed in a sentence such that it appears to modify the wrong noun, often because the intended noun is missing.
- The Bug: "After coding for six hours, the coffee was cold." (This implies the coffee was coding).
- The Fix: "After coding for six hours, the engineer realized the coffee was cold."
Pronoun-Antecedent Agreement
A pronoun must agree in number and gender with the noun it replaces (the antecedent).
- The Bug: "Every developer must submit their code." (Historically, "their" was considered plural, though modern usage increasingly accepts the "singular they" for inclusivity).
- The Fix (Traditional): "Every developer must submit his or her code."
- The Fix (Modern/Inclusive): "Developers must submit their code." (Pluralizing the antecedent is often the cleanest solution).
Citation of Non-Traditional Sources
In the digital age, documenting sources like software repositories, datasets, or AI-generated content requires specific adaptations of standard styles.
- Software: Cite the version number and the repository URL.
- AI (LLMs): Most styles (MLA/APA) now require citing the AI model (e.g., ChatGPT-4), the developer (OpenAI), and the date the prompt was executed, often including the prompt itself in an appendix.
Summary of Best Practices
- Prioritize Clarity: Use active verbs and avoid unnecessary jargon.
- Maintain Consistency: Choose one documentation style and apply it rigorously.
- Audit for Bias: Use inclusive language to ensure the text is accessible to a diverse audience.
- Verify Mechanics: Use automated tools (linters, spellcheckers) but perform a final manual "code review" of your prose to catch subtle logical errors.
Source Materials
Study Writing Guide on Lykke
This course page is free to open: signed out, you can read its first two sections, and signing in, on any plan, opens the rest. The free Lykke Chrome extension syncs your own Canvas courses, so ChatGPT, Claude and Muse can answer from your classes and deadlines. It only reads Canvas.
Add the free extensionSign in to open every section