Notes ✏️

Writing gotchas and tips

4 min read

Technical Writing

  • Use active voice instead of passive voice for stories/documentations. Example: “The values will be hardcoded.” (passive) vs “We will hardcode the values.” (active). Passive voice is not the best in this case, because:
    • (a) It hides the actor
    • (b) It makes sentences longer and harder to read
    • (c) It feels indirect and less confident When passive voice is fine Passive is OK when:
    • The actor doesn’t matter: “The service is deployed nightly.”
    • You want to emphasise the result, not the doer.
    • In formal academic writing. But in product specs, PRs, tech decisions, and design notes, active is almost always better.

📝 Technical Writing Guide (for Engineers) (by ChatGPT)

1. Prefer Short Sentences

Break long thoughts into 2–3 clear sentences.

Bad:

The slider is hard to use because the data is skewed and the min/max becomes extreme, stretching the UI.

Good:

The dataset has extreme outliers.
They stretch the computed slider range.
So we use fixed bounds.

2. Use Active Voice

Active voice is clearer and more direct.

Passive:

The values will be hardcoded.

Active:

We will hardcode the values.

3. Put the “Why” Before the “What”

Readers understand decisions better in this order:

  1. Reason

  2. Decision

Example:

Outliers distort the slider range.
So we use fixed min–max bounds.

4. Prefer Concrete Over Abstract

Avoid vague words (e.g., extreme, sensible, significant). Use specific examples.

Bad:

The data is skewed.

Good:

Most companies fall between –10 and 40, but some go from –100 to 200.

5. Remove Filler Words

Cut words like: basically, actually, in order to, rather than, due to the fact that.

Bad:

In order to fix this, we basically changed…

Good:

To fix this, we changed…

6. Use Simple, Familiar Words

Prefer plain English.

  • use → utilize

  • help → assist

  • find out → ascertain

  • start → commence

Simple is clearer.

7. Avoid Hidden Complexity

Don’t bury the key point inside a long sentence.

Bad:

The slider is hardcoded to avoid issues caused by the min and max values being computed from skewed data.

Good:

The dataset has extreme outliers.
These stretch the computed range.
To avoid this, we use fixed bounds.

8. Prefer Structure Over Paragraphs

When listing multiple points, use bullets.

Bad:

We chose this because it’s fast, easy to maintain, and consistent.

Good:

We chose this because it’s:

  • fast

  • easy to maintain

  • consistent

9. Use Parallel Structure

Parallel phrasing reads smoother.

Not parallel:

The slider improves usability and performance is better.

Parallel:

The slider improves usability and improves performance.

10. Write for Skim-Readers

Assume readers skim.

Use:

  • headers

  • bullets

  • short paragraphs

  • bold key phrases

  • examples

⭐ The 3-Sentence Rule

Use this format for any explanation:

  1. What problem exists

  2. Why it matters

  3. What you decided to do

Example:

  1. The dataset has extreme outliers.

  2. These stretch the computed slider range.

  3. We’re using fixed bounds (–10 to 40) and allowing custom input.

✅ Technical Writing Checklist (for PRs, Design Docs, Comments)

Use this when reviewing your writing:

Clarity

  •  Is each sentence short and focused on one idea?

  •  Did I use active voice?

  •  Are explanations reason → decision?

  •  Did I remove filler words?

  •  Are examples concrete and specific?

Structure

  •  Did I break long paragraphs into smaller chunks?

  •  Did I use bullets where helpful?

  •  Did I use headers for sections?

  •  Did I include an example when introducing something abstract?

Audience Awareness

  •  Can a skim-reader understand the main point in under 10 seconds?

  •  Did I avoid overly academic or fancy words?

  •  Did I explain why before telling people what I changed?

Technical Accuracy

  •  Did I avoid ambiguous terms?

  •  Are numbers, ranges, and assumptions explicit?

  •  Is the reasoning traceable?

⭐ Quick Templates

Decision Explanation

Problem: <1 sentence>  
Impact: <1 sentence>  
Decision: <1 sentence>  
Alternatives considered: <optional>

PR Description

### What changed?
- <bullet list>

### Why?
- <explain reason before action>

### How to test?
- <steps>

### Notes
- <edge cases, follow-ups>

Other

“Let’s” (with an apostrophe)

  • Used similar to “let us”

“Lets” (without apostrophe)

  • lets means you are letting someone do something. He lets the kid play all day.

“Its” (no apostrophe):

  • Used to show possession, meaning “belonging to it”.
  • Examples:
    • “The dog wagged its tail.”

“It’s” (with an apostrophe):

  • A contraction, meaning “it is” or “it has”.

    • Examples:“It’s raining outside.” (meaning “it is raining”)

  • If you have expanded an acronym once, just use the acronym. Don’t keep repeating the acronym with full form.

  • don’t write the new tuple(which, Let there be space before starting the bracket.

Resources

techwriting communication engineering