✍️ Writing Exercises

IT professionals write: Jira tickets and bug reports, pull request descriptions, commit messages, technical documentation (API docs, ADRs, RFCs), post-incident reports, project proposals, stakeholder updates, code comments, README files, and internal wiki articles. Each has its own conventions, register, and structure that these exercises help you master.

A good bug report includes: (1) Clear title in imperative form — "Login button fails on mobile Safari"; (2) Environment — OS, browser, version; (3) Steps to reproduce — numbered, specific; (4) Expected behaviour; (5) Actual behaviour; (6) Screenshots or logs. Vague reports like "it doesn't work" are useless. Good bug reports save hours of developer time.

A good PR description includes: What changes were made (summary), Why the change was needed (context/motivation), How to test the change (testing instructions), Screenshots for UI changes, and links to related tickets. Avoid PR descriptions that just repeat the commit message or say "minor fixes". Good descriptions speed up code review and reduce back-and-forth.

Follow the conventional commits format: "type(scope): description" — e.g., "fix(auth): handle expired JWT tokens", "feat(api): add pagination to /users endpoint". The description should be imperative, present tense, and under 72 characters. The body (optional) explains WHY not WHAT. Common types: feat, fix, docs, chore, refactor, test, style.

An ADR documents an important architectural decision, its context, and its consequences. Standard structure: Title, Status (proposed/accepted/deprecated), Context (why this decision was needed), Decision (what was decided), Consequences (trade-offs, implications). Writing clear ADRs creates institutional memory and prevents relitigating past decisions. They're short — typically one page.

Good code comments explain WHY, not WHAT (the code shows what). Comment types: (1) intent comments — "// Using polling because WebSocket causes issues in Safari"; (2) warning comments — "// Don't change this order — breaks legacy API"; (3) TODO comments with tickets; (4) API documentation (JSDoc, docstrings). Avoid commenting obvious code: "// increment i by 1" for i++ is noise.

Hedging language expresses appropriate uncertainty: "This approach may improve performance by approximately 20%", "In most cases, this configuration should work". Hedging is professional and honest — it distinguishes claims from facts and sets realistic expectations. Overclaiming ("this will definitely fix it") damages trust if wrong. Technical writers and engineers should hedge appropriately.

Post-incident report structure: (1) Incident summary — what happened, when, impact; (2) Timeline — chronological sequence of events; (3) Root cause analysis; (4) Contributing factors; (5) What went well; (6) Action items with owners and deadlines. Use blameless language — focus on systems, not individuals. Keep it factual, not defensive.

Common mistakes: (1) Passive voice overuse making ownership unclear; (2) Jargon without explanation; (3) Assuming prior knowledge; (4) No table of contents for long documents; (5) Outdated information left uncorrected; (6) Vague action items without owners; (7) Wall-of-text paragraphs without headings. Good technical writing is specific, scannable, and maintained.

Practice strategies: read and analyse well-written open-source READMEs and ADRs, volunteer to write team documentation, ask for writing feedback during code reviews, study the Google Developer Documentation Style Guide (free online), and practise rewriting existing documentation to be clearer. The exercises on this page provide structured practice with immediate feedback.