Articles tagged: Writing
Accessibility in technical documentation does not end with navigation and contrast. Code examples, JSON responses, reference tables, and explanatory diagrams must also remain understandable, scannable, and usable without relying only on color.
A technically valid request is not automatically a useful example. Choose examples that expose the mental model, show realistic values and let a developer predict what to do next. An example copied from a schema can be syntactically correct and still teach nothing.
Good authentication docs explain the whole credential lifecycle: obtaining access, sending credentials, rotating them and diagnosing failure. Explain prerequisites, roles, environments and credential issuance before the first HTTP request.
A useful reading list is no longer a shelf of classics. Compare actively maintained Microsoft, Google, GitHub and IBM guidance, use Diátaxis to test content structure, and turn each reading session into a concrete documentation exercise.
Reading about documentation helps, but skill grows faster when you repeatedly perform small research, restructuring, editing and verification exercises with clear feedback. “Improve technical writing” is too broad to train.
Text-defined diagrams are maintainable and reviewable, but only when the visual problem matches what the notation can express clearly. Use text-defined diagrams for flows, states, dependencies and sequences where relationships are the main information.
An error reference is useful only when it helps a developer identify the condition, understand the response and choose a safe next action. Describe the condition that triggers an error, not only a status code and message.
Good API documentation combines machine-readable contracts with human explanations, runnable examples and explicit error behavior. REST API documentation has two audiences at once: machines and people.
Short repeated editing exercises train diagnosis: finding ambiguity, missing conditions, weak structure and unnecessary words in real documentation. Practice one defect at a time: prerequisites, vague verbs, terminology, long sentences or missing outcomes.
Markdown stays simple only when a team agrees on structure, metadata and extensions before thousands of files make every exception permanent. Standardize filenames, frontmatter, headings, image locations and internal-link conventions early.
An OpenAPI description can generate accurate reference structure, but developers still need concepts, task flows, authentication guidance, examples and failure recovery that a schema alone cannot explain. OpenAPI is excellent at describing operations, parameters, request and response shapes, status codes and reusable schemas.
Release notes become useful when they explain consequences, decisions and required actions instead of mirroring an internal ticket list. An internal changelog is not a user message; translate implementation into consequences.