Comment Smells: When to Delete, When to Explain Intent

Path Outline

Progress0%

1Docs as Engineering: Requirements, Change Control, and Outcomes 2Audience, Reader State, and the Intake That Prevents Wrong Docs 3From “Document X” to a Task Statement and Success Metric 4The Omission Pass: Cutting Anything That Doesn’t Serve the Task 5A Reusable Definition of Done and a One-Page Doc Brief

6The Four Diátaxis Types as Reader Behaviors 7Classifying Doc Requests With Audience, Task, and Success 8Diagnosing Mixed-Type Docs by Their Failure Signals 9Restructuring a Mixed Page Into Clean Doc Types 10Quality Checklists and Navigation Cues That Prevent Remixing 11Intake and Peer Review to Keep Each Section Single-Intent

12Define the README’s Onboarding Job and Success Metric 13Write a Quickstart That Proves First Success 14State Prerequisites and Environment Assumptions Without Over-Specifying 15Build a Verifiable Run Locally Path With Recovery Notes 16Write Troubleshooting That Matches Predictable Failure Modes 17Separate Intent, Add Support Pointers, and Run a Cold-Start Review

18Define the Reference Promise and Scope 19Build a Reference Template You Can Reuse 20Document Auth and Permissions Without Leaking Secrets 21Specify Parameters So They Can’t Be Misread 22Make Responses and Errors Testable 23Write Examples That Prove the Contract 24Document Side Effects and Verify the Entry End-to-End

25Pick the Task and Define “Done”26Prerequisites That Prevent Mid-Procedure Failure 27Numbered Steps That Are Easy to Execute Under Time Pressure 28Verification After Key Steps: Make Progress Observable 29Variants Without Bloat: Controlled Forks and Links to Reference 30Diátaxis Separation and the Peer Execution Test

31Triggers and Boundaries: When a Runbook Applies 32Immediate Safety Checks and Blast-Radius Control 33Diagnosis First: Evidence Capture and Interpretation 34Mitigation Steps With Verification Gates and Stop Conditions 35Rollback and the Minimum Safe State 36Escalation Paths and What to Hand Off 37Communication Placeholders and Tabletop Verification

38Start With the Decision and the Reviewers 39Write a Problem Statement Reviewers Can Test 40Goals and Non-Goals That Stop Scope Creep 41Constraints and Assumptions Without Fake Precision 42Proposed Approach at Two Zoom Levels 43Alternatives and Rejection Rationale Reviewers Trust 44Rollout, Rollback, and a Structured Review That Lands a Decision

45The Smallest ADR That Still Answers “Why?”46Fill a MADR Template From an Accepted RFC 47Make ADRs Discoverable in a Repository 48Link ADRs to the RFC and the Code That Enforces Them 49Supersede an ADR Without Losing History 50Review ADRs by Answering the Only Question That Matters

51Mapping Inline Docs to Audiences and Risk 52Docstrings as Contracts: Inputs, Outputs, Errors, and Invariants

53Comment Smells: When to Delete, When to Explain Intent

54Lying Comments: Reconciling Docs With Real Behavior 55Documenting Edge Cases and Failure Behavior Without Bloat 56Linking Code to the Doc Set and Enforcing Inline Docs in Review

57Terminology Audits and the Mini-Glossary 58From Vague Steps to Explicit Actors and Objects 59Editing for Scannability Without Losing Accuracy 60Removing Weasel Words by Adding Scope or Numbers 61Making Troubleshooting Actionable: Symptom → Cause → Fix 62Runbook Edits for a Reader Under Pressure 63Peer Editing and the PR-Ready Checklist

64When a Diagram Beats Prose 65Choosing Diagram Type by the Reader’s Question 66Scope, Legend, and Naming That Prevent Diagram Drift 67A Sequence Diagram for One Request End-to-End 68A Runbook Decision Flow With Stop Conditions and Escalation 69Architecture Boundaries, Text Alignment, and Peer Review

70Docs-as-Code: The Minimal Workflow Contract 71The Docs PR Checklist That Catches Real Failures 72A Minimal CI Plan for Docs Checks (Tool-Agnostic)73Where Linting Helps: Markdown vs. Prose Checks 74Sketching a GitHub Actions Check Without Getting Trapped in YAML 75Ownership, Staleness, and Update Triggers 76Deprecation and the One-PR Maintenance Drill

Hide outline

Home
Paths
Technical Writing for Software Engineers
Comment Smells: When to Delete, When to Explain Intent