up:: [[Technical Writing MOC]] tags:: #on/technical-writing # Some Technical Writing Basics These are my notes on the basics of technical writing. ## Some Grammar and Parts of Speech | **Part of Speech** | **Definition** | | ---- | ---- | | Noun | A person, place, concept, or thing | | Pronoun | A noun that replaces another noun or larger structure | | Adjective | A word or phrase that modifies a noun | | Verb | An action word or phrase | | Adverb | A word or phrase that modifies a verb, an adjective, or another adverb | | Preposition | A word or phrase specifying the positional relationship of two nouns | | Conjunction | A word that connects two nouns or phrases | | Transition<br> | A word or phrase that connects two sentences | ### Nouns - Represent people, places, or things - In programming, you can think of classes and variables as nouns ### Pronouns - Substitutions for other nouns or sentences - Example: Julianne likes to code. **She** is a great software engineer. - Example: Many people do not do debugging. **This** is poor engineering. ### Verbs - Action words or phrases - Represent the relationship between two nouns (an actor and a target) - Identifies what the actor does to the target - Sentences can contain multiple verbs - Could consist of multiple words (Example: **was eating**) - Each sentence must contain at least one verb ### Adjectives and Adverbs - Adjectives modify nouns, adverbs modify verbs, adjectives, and other adverbs - Adverbs don't necessarily have to be right next to their verb ### Prepositions - Specify the relationship between two things - Example: The book is **on** the table. - Example: The appointment is **before** noon. - Example: Quiet **by** Susan Cain is my favorite book. ### Conjunctions and Transitions - Conjunctions connect phrases or nouns within a sentence - Transitions connect sentences themselves - Most important conjunctions: **and**, **but**, **or** - Most important transitions: **However**, **Therefore**, **For example** ## Words These are some tips about using words in your writing. ### Define new or unfamiliar terms - Recognize terms that may be unfamiliar to your target audience - When spotting such a term, do one of the following: - If the term already exists, link to an existing explanation - If you're introducing the term, define it. If you're introducing many terms, collect them into a glossary ### Use terms consistently - Apply the same unambiguous word or term consistently throughout your document - You may introduce a shortened name for something and then use that - Example: Protocol Buffers (or protobufs for short)... ### Use acronyms properly - On initial use, spell out the full term and then put the acronym in parentheses - Put both in bold face - Do not cycle back-and-forth between the acronym and the expanded version in the same document - Guidelines for using acronyms - Don't define acronyms that would only be used a few times - Do define acronyms that meet the following criteria: - The acronym is significantly shorter than the full term - The acronym appears many times in the document ### Recognize ambiguous pronouns - Using pronouns improperly is like having a null pointer error - Pronoun guidelines: - Only use a pronoun *after* you've introduced the noun - Place the pronoun as close as possible to the referring noun - If more than five words separate them, then consider repeating the noun instead of using the pronoun - If you introduce a second noun between your noun and your pronoun, reuse your noun instead of using a pronoun ## Active Voice The majority of sentences in technical writing should be in active voice. ### Distinguish Between Active Voice and Passive Voice In **active voice**, an actor acts on a target. Active voice sentences follow this formula: ``` Active Voice Sentence = actor + verb + target ``` **Passive voice** follows the reverse: ``` Passive Voice Sentence = target + verb + actor ``` #### Examples **Active Voice**: The player kicked the ball. **Passive Voice**: The ball was kicked by the player. ### Recognize Passive Verbs Passive verbs typically follow this formula: ``` passive verb = form of be + past participle verb ``` - A form of *be* in a passive verb is usually one of the following words: - is/are - was/were - The *past participle verb* is a plain verb plus the suffix *ed*. For example: - interpreted - generated - formed - Some past participle verbs are irregular, such as: - sat - known - frozen - Examples of passive verbs: - was interpreted - is generated - was formed - is frozen - If the phrase contains an actor, a preposition often follows the passive verb - was interpreted as - is generated by - was formed by - is frozen by ### Imperative Verbs are typically active - Easy to misclassify sentences starting with an imperative verb as passive - An **imperative verb** is a command - Sentences that start with imperative verbs are typically in active voice, even though they don't specify an actor - They imply an actor, and the actor is **you** ### Prefer Active Voice to Passive Voice Active voice provides the following advantages: - most readers mentally convert passive voice to active voice - passive voice obfuscates ideas, reports action indirectly - some passive voice sentences omit an actor, forcing the reader to guess - active voice is generally shorter ## References - [developers.google.com - Technical Writing](https://developers.google.com/tech-writing)