Question 1

What is technical writing, and what makes documentation good?

Accepted Answer

Writing whose purpose is to help someone **do something or understand something**, judged entirely by whether they succeed — which makes it the one form of writing with an objective quality test.

**The types, which have different jobs and are frequently conflated into an unusable mess:**

**Tutorials** — learning-oriented. A beginner follows steps to a working result. **The goal is confidence, not completeness**, and a tutorial that explains every option fails.

**How-to guides** — task-oriented. A competent user achieves a specific goal. Assumes context, omits teaching.

**Reference** — information-oriented. Complete, accurate, consistently structured, consulted rather than read.

**Explanation** — understanding-oriented. Background, reasoning, alternatives considered, why it works this way.

**This four-way split is the single most useful idea in the field**, because most bad documentation is a tutorial interrupted by reference material and an argument about design philosophy.

**What makes documentation actually good:**

**It is written for a stated reader** with stated prior knowledge.

**It is task-oriented** where tasks are what the reader has. People arrive wanting to do something, not to learn your architecture.

**It is tested by someone following it**, which catches the steps the author knew and omitted. **The curse of knowledge is the fundamental problem**, and only an outsider reveals it.

**Examples are complete and runnable**, since a fragment requiring assembly is a puzzle.

**It states prerequisites and expected outcomes** up front.

**It says what to do when it goes wrong**, which is where readers actually are when reading.

**It is findable**, since undiscoverable documentation does not exist.

**It is maintained**, and wrong documentation is worse than none because it is trusted.

**The craft specifics:** the imperative mood for instructions; one action per step; consistent terminology, since synonyms that aid prose harm reference; screenshots used sparingly, as they date fastest; and version labelling.

**Docs-as-code** — keeping documentation in version control alongside the software, reviewed in the same pull request — is the practice most associated with documentation staying accurate.

Question 2

How do you actually get better at writing?

Accepted Answer

Through a small number of practices that reliably work, and they are less appealing than the advice people usually seek. Read closely, not just widely. Reading a great deal helps by exposure, but the

Question 3

What is plain English and why does it matter?

Accepted Answer

Plain English is writing designed so the intended reader can understand it the first time, at the speed they normally read. It is not simplified English, not dumbing down, and not short words for

Question 4

What is a topic sentence and why does it make writing easier to read?

Accepted Answer

A topic sentence states what a paragraph is about, usually as its first sentence. Everything else in the paragraph then supports, develops, qualifies or illustrates it. Why it works comes down to how

Question 5

How do you research a novel without drowning in it?

Accepted Answer

By researching to a question rather than to a subject, and by accepting that most of what you learn will not appear on the page — which is the point, not a waste. Why research becomes a trap. It

Question 6

How do you edit your own writing?

Accepted Answer

By separating the passes — because editing for structure, for sentences and for errors are different activities using different attention, and attempting them simultaneously produces a polished

Question 7

How do you write a good opening?

Accepted Answer

By giving the reader a reason to continue within the first paragraph — which usually means a question, a tension, or a voice worth following, rather than the explanation most first drafts begin with.

Related Questions