Only tips I am writing here which I think I am not doing in writing.
When writing or editing, learn to recognize terms that might be unfamiliar to some or all of your target audience. When you spot such a term, take one of the following two tactics:
- If the term already exists, link to a good existing explanation. (Don't reinvent the wheel.)
- If your document is introducing the term, define the term. If your document is introducing many terms, collect the definitions into a glossary.
Here are the guidelines for acronyms:
- Don't define acronyms that would only be used a few times.
- Do define acronyms that meet both of the following criteria:
- The acronym is significantly shorter than the full term.
- The acronym appears many times in the document.
Consider the following pronoun guidelines:
- Only use a pronoun after you've introduced the noun; never use the pronoun before you've introduced the noun.
- Place the pronoun as close as possible to the referring noun. In general, if more than five words separate your noun from your pronoun, 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.
Problematic Pronouns: This, That, Them, They, It, Their
Use the active voice most of the time. Use the passive voice sparingly. Active voice provides the following advantages:
- Most readers mentally convert passive voice to active voice. Why subject your readers to extra processing time? By sticking to active voice, you enable readers to skip the preprocessor stage and go straight to compilation.
- Passive voice obfuscates your ideas, turning sentences on their head. Passive voice reports action indirectly.
- Some passive voice sentences omit an actor altogether, which forces the reader to guess the actor's identity.
- Active voice is generally shorter than passive voice.
Be bold—be active.
To engage and educate readers, choose precise, strong, specific verbs. Reduce imprecise, weak, or generic verbs, such as the following:
- forms of be: is, are, am, was, were, etc.
Note that generic verbs often signal other ailments, such as:
- an imprecise or missing actor in a sentence
- a passive voice sentence
Sentences that start with There is or There are marry a generic noun to a generic verb. Generic weddings bore readers. Show true love for your readers by providing a real subject and a real verb.
In the best-case scenario, you may simply delete There is or There are (and possibly another word or two later in the sentence).
- Focus each sentence on a single idea. Focus each sentence on a single idea, thought, or concept. Just as statements in a program execute a single task, sentences should execute a single idea.
- Convert some long sentences to lists
- Eliminate or reduce extraneous words
at this point in time
determine the location of
is able to
- Reduce subordinate clauses:
Subordinate clauses modify the idea in the main clause. As the name implies, subordinate clauses are less important than the main clause. For example, consider the following sentence:
Python is an interpreted programming language, which was invented in 1991.
- main clause: Python is an interpreted programming language
- subordinate clause: which was invented in 1991
If you read a sentence aloud and hear a pause just before the subordinate clause, then use which. If you don't hear a pause, use that. Go back and read the preceding two example sentences. Do you hear the pause in the first sentence?
Place a comma before which; do not place a comma before that.
What separates effective lists from defective lists? Effective lists are parallel; defective lists tend to be nonparallel. All items in a parallel list look like they "belong" together. That is, all items in a parallel list match along the following parameters:
- logical category
Consider starting all items in a numbered list with an imperative verb. An imperative verb is a command, such as open or start. For example, notice how all of the items in the following parallel numbered list begin with an imperative verb:
- Download the Frambus app from Google Play or iTunes.
- Configure the Frambus app's settings.
- Start the Frambus app.
Analytic minds tend to love tables. Given a page containing multiple paragraphs and a single table, engineers' eyes zoom towards the table.
Consider the following guidelines when creating tables:
- Label each column with a meaningful header. Don't make readers guess what each column holds.
- Avoid putting too much text into a table cell. If a table cell holds more than two sentences, ask yourself whether that information belongs in some other format.
- Although different columns can hold different types of data, strive for parallelism within individual columns. For instance, the cells within a particular table column should not be a mixture of numerical data and famous circus performers.
The opening sentence is the most important sentence of any paragraph. Busy readers focus on opening sentences and sometimes skip over subsequent sentences. Therefore, focus your writing energy on opening sentences.
Good opening sentences establish the paragraph's central point.
A paragraph should represent an independent unit of logic. Restrict each paragraph to the current topic. Don't describe what will happen in a future topic or what happened in a past topic. When revising, ruthlessly delete (or move to another paragraph) any sentence that doesn't directly relate to the current topic.
Good paragraphs answer the following three questions:
- What are you trying to tell your reader?
- Why is it important for the reader to know this?
- How should the reader use this knowledge? Alternatively, how should the reader know your point to be true?
For example, the following paragraph answers what, why, and how:
good documentation = knowledge and skills your audience needs to do a task − your audience's current knowledge and skills
In other words, make sure your document provides the information that your audience needs but doesn't already have. Therefore, this unit explains how to do the following:
- Define your audience.
- Determine what your audience needs to learn.
- Fit documentation to your audience.
Engineers and scientists are busy people who won't necessarily read all 76 pages of your design document. Imagine that your peers might only read the first paragraph of your document. Therefore, ensure that the start of your document answers your readers' essential questions.
Professional writers focus considerable energy on page one to increase the odds of readers making it to page two. However, the start of any long document is the hardest page to write. Be prepared to revise page one many times.
In your career, no matter how creative you are, you will author precious few documents containing truly revolutionary ideas. Most of your work will be evolutionary, building on existing technologies and concepts. Therefore, compare and contrast your ideas with concepts that your audience already understands. For example:
This new app is similar to the Frambus app, except with much better graphics.
The Froobus API handles the same use cases as the Frambus API, except that the Froobus API is much easier to use.
⚠️Disclaimer: All the screenshots, materials, and other media documents used in this article are copyrighted to the original platform or authors.