https://techwriters.org/Technical writing, documentation engineering, tools and the profession.https://techwriters.org/articles/accessible-code-examples-and-tables/https://techwriters.org/articles/accessible-code-examples-and-tables/Thu, 13 Aug 2026 00:00:00 GMTAccessibility 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.https://techwriters.org/articles/ai-as-editor-not-oracle/https://techwriters.org/articles/ai-as-editor-not-oracle/Thu, 13 Aug 2026 00:00:00 GMTAI is often more useful when it challenges structure, ambiguity and omissions than when it is treated as the authority that decides what is true. Separate language work from truth: a clearer sentence can still describe incorrect behavior.https://techwriters.org/articles/ai-fact-checking-for-docs/https://techwriters.org/articles/ai-fact-checking-for-docs/Thu, 13 Aug 2026 00:00:00 GMTGenerative text can sound complete while quietly inventing defaults, guarantees or citations. Build a verification pass around authoritative sources, executable examples and explicit uncertainty. The dangerous AI error in documentation is rarely broken grammar.https://techwriters.org/articles/ai-learned-to-write-documentation/https://techwriters.org/articles/ai-learned-to-write-documentation/Thu, 13 Aug 2026 00:00:00 GMTIn three years, generative AI turned a first draft from an expensive output into a cheap operation. The important question is no longer whether a model can write, but who owns facts, structure, review, updates, and quality once text can be produced in minutes.https://techwriters.org/articles/api-examples-that-teach/https://techwriters.org/articles/api-examples-that-teach/Thu, 13 Aug 2026 00:00:00 GMTA 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.https://techwriters.org/articles/authentication-docs-that-prevent-support-tickets/https://techwriters.org/articles/authentication-docs-that-prevent-support-tickets/Thu, 13 Aug 2026 00:00:00 GMTGood 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.https://techwriters.org/articles/books-and-guides-for-technical-writers/https://techwriters.org/articles/books-and-guides-for-technical-writers/Thu, 13 Aug 2026 00:00:00 GMTA 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.https://techwriters.org/articles/choosing-a-docs-generator/https://techwriters.org/articles/choosing-a-docs-generator/Thu, 13 Aug 2026 00:00:00 GMTSphinx, MkDocs, Astro and other generators optimize for different content models and teams. Choose by authoring workflow, extensibility, localization and maintenance cost instead of feature-list enthusiasm. A generator demo can look excellent and still be wrong for your documentation.https://techwriters.org/articles/choosing-search-for-docs/https://techwriters.org/articles/choosing-search-for-docs/Thu, 13 Aug 2026 00:00:00 GMTDocumentation search should be selected and tuned around the queries users fail to resolve, not around a feature checklist from vendors. Search is most valuable when readers know a term or symptom but not where the information lives.https://techwriters.org/articles/deliberate-practice-for-docs/https://techwriters.org/articles/deliberate-practice-for-docs/Thu, 13 Aug 2026 00:00:00 GMTReading 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.https://techwriters.org/articles/diagrams-as-code-in-documentation/https://techwriters.org/articles/diagrams-as-code-in-documentation/Thu, 13 Aug 2026 00:00:00 GMTText-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.https://techwriters.org/articles/docs-as-code-without-fanaticism/https://techwriters.org/articles/docs-as-code-without-fanaticism/Thu, 13 Aug 2026 00:00:00 GMTDocs-as-Code does not mean forcing every writer into an IDE. This guide covers the full workflow: browser editing, Git, previews, useful automated checks, human review, publication, and a transparent way to measure time savings without inventing benchmarks.https://techwriters.org/articles/docs-tools-then-and-now/https://techwriters.org/articles/docs-tools-then-and-now/Thu, 13 Aug 2026 00:00:00 GMTThe formats and delivery pipelines changed dramatically, but the durable problems are familiar: source control, reuse, navigation, review and keeping published information synchronized with the product. Long before Docs-as-Code became a label, documentation teams struggled with multiple source files, reused fragments, versioned manuals and the question of which copy was current.https://techwriters.org/articles/documentation-debt-triage/https://techwriters.org/articles/documentation-debt-triage/Thu, 13 Aug 2026 00:00:00 GMTA practical way to separate harmless old pages from documentation debt that creates support work, failed tasks and release risk. Age alone does not create debt; user failure and maintenance cost do.https://techwriters.org/articles/documentation-in-ci-cd/https://techwriters.org/articles/documentation-in-ci-cd/Thu, 13 Aug 2026 00:00:00 GMTTreat documentation as a build artifact: validate structure, links, examples and publication rules before changes reach readers. CI cannot decide whether an explanation is useful, but it can reject many predictable defects before a human spends time on them.https://techwriters.org/articles/documentation-lead-without-bureaucracy/https://techwriters.org/articles/documentation-lead-without-bureaucracy/Thu, 13 Aug 2026 00:00:00 GMTA documentation lead should reduce uncertainty, not create another approval layer. Define ownership, standards and escalation paths while keeping routine publishing fast and close to the people who know the product. When documentation grows across several teams, somebody eventually asks for central control.https://techwriters.org/articles/documentation-metrics-that-matter/https://techwriters.org/articles/documentation-metrics-that-matter/Thu, 13 Aug 2026 00:00:00 GMTMeasure whether documentation helps users complete work and helps teams maintain knowledge, not merely how often pages were opened. Traffic is context, not success; a popular page can be popular because it is confusing.https://techwriters.org/articles/documentation-ownership-map/https://techwriters.org/articles/documentation-ownership-map/Thu, 13 Aug 2026 00:00:00 GMTDefine who decides, who reviews and who maintains each documentation area without creating a matrix nobody wants to update. Ownership means authority and responsibility for a domain, not writing every sentence.https://techwriters.org/articles/documentation-review-workflow/https://techwriters.org/articles/documentation-review-workflow/Thu, 13 Aug 2026 00:00:00 GMTA review process should make responsibility visible, reduce waiting and separate factual, editorial and product approval. Documentation review fails when nobody knows who must act next.https://techwriters.org/articles/documenting-api-errors/https://techwriters.org/articles/documenting-api-errors/Thu, 13 Aug 2026 00:00:00 GMTAn 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.https://techwriters.org/articles/documenting-rest-api/https://techwriters.org/articles/documenting-rest-api/Thu, 13 Aug 2026 00:00:00 GMTGood 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.https://techwriters.org/articles/editing-drills-for-technical-writers/https://techwriters.org/articles/editing-drills-for-technical-writers/Thu, 13 Aug 2026 00:00:00 GMTShort 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.https://techwriters.org/articles/entering-technical-writing/https://techwriters.org/articles/entering-technical-writing/Thu, 13 Aug 2026 00:00:00 GMTThree years ago, a beginner could enter the field by writing clearly, learning a few tools, and building a portfolio. In 2026 the entry bar is higher: AI drafts the easy material, teams are leaner, and new technical writers are increasingly expected to verify facts, work with docs-as-code and APIs, and own documentation as a system.https://techwriters.org/articles/first-90-days-in-documentation-team/https://techwriters.org/articles/first-90-days-in-documentation-team/Thu, 13 Aug 2026 00:00:00 GMTA new technical writer learns faster by mapping the product, users, publishing system and decision makers before trying to rewrite everything. First month: map product areas, audiences, source repositories, build, reviewers and release flow.https://techwriters.org/articles/forum-questions-that-aged-well/https://techwriters.org/articles/forum-questions-that-aged-well/Thu, 13 Aug 2026 00:00:00 GMTTool names change faster than editorial problems. Questions about terminology, ownership, screenshots, reuse and review still appear in documentation teams because they are symptoms of deeper system design choices. The tooling answer changed from shared folders to repositories and ownership files, but the organizational question did not.https://techwriters.org/articles/glossaries-and-terminology/https://techwriters.org/articles/glossaries-and-terminology/Thu, 13 Aug 2026 00:00:00 GMTA glossary becomes useful when it controls decisions across products, interfaces and documentation instead of merely collecting words. A useful terminology entry answers more than “what does this word mean?”.https://techwriters.org/articles/hiring-technical-writers-without-trick-tests/https://techwriters.org/articles/hiring-technical-writers-without-trick-tests/Thu, 13 Aug 2026 00:00:00 GMTA practical hiring process should reveal how a writer understands users, verifies facts and improves information — not reward unpaid marathon assignments. Test the work the role actually requires instead of grammar puzzles and obscure trivia.https://techwriters.org/articles/hypertext-before-modern-docs-portals/https://techwriters.org/articles/hypertext-before-modern-docs-portals/Thu, 13 Aug 2026 00:00:00 GMTMany modern documentation patterns began as older hypertext problems: how to split information, name destinations and help readers recover when they get lost. Hypertext gave readers freedom from a linear manual and immediately created orientation problems.https://techwriters.org/articles/information-architecture-for-growing-docs/https://techwriters.org/articles/information-architecture-for-growing-docs/Thu, 13 Aug 2026 00:00:00 GMTA documentation tree that works at fifty pages can fail at five hundred. Build navigation around user tasks, content types and durable concepts before the archive becomes a map of the org chart. Small documentation sets can survive almost any navigation scheme.https://techwriters.org/articles/learn-api-docs-by-building-a-small-api/https://techwriters.org/articles/learn-api-docs-by-building-a-small-api/Thu, 13 Aug 2026 00:00:00 GMTA tiny working API gives a technical writer enough surface area to practice reference, concepts, examples, errors and onboarding without a large project. Keep the API intentionally small; the goal is documentation practice, not backend engineering.https://techwriters.org/articles/llm-content-pipeline-guardrails/https://techwriters.org/articles/llm-content-pipeline-guardrails/Thu, 13 Aug 2026 00:00:00 GMTIf a model can create or update documentation at scale, validation must scale with it. Constrain inputs, preserve provenance, validate structure and make publication a separate privileged step. A useful architecture assumes the model will sometimes be wrong.https://techwriters.org/articles/markdown-at-scale/https://techwriters.org/articles/markdown-at-scale/Thu, 13 Aug 2026 00:00:00 GMTMarkdown 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.https://techwriters.org/articles/openapi-as-source-not-documentation/https://techwriters.org/articles/openapi-as-source-not-documentation/Thu, 13 Aug 2026 00:00:00 GMTAn 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.https://techwriters.org/articles/portfolio-for-technical-writer/https://techwriters.org/articles/portfolio-for-technical-writer/Thu, 13 Aug 2026 00:00:00 GMTHiring teams need evidence of how you investigate, structure and verify documentation. A strong portfolio explains the problem, constraints, process and result instead of displaying isolated polished screenshots. A polished article shows that you can produce polished text.https://techwriters.org/articles/release-notes-users-can-act-on/https://techwriters.org/articles/release-notes-users-can-act-on/Thu, 13 Aug 2026 00:00:00 GMTRelease 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.https://techwriters.org/articles/structured-writing-rules-that-scale/https://techwriters.org/articles/structured-writing-rules-that-scale/Thu, 13 Aug 2026 00:00:00 GMTConsistency at scale comes from content models, terminology and reusable patterns, not from asking every contributor to memorize a giant style guide. Encode the rules that matter in schemas and components. A small team can rely on shared habits and direct editing.https://techwriters.org/articles/style-guide-people-use/https://techwriters.org/articles/style-guide-people-use/Thu, 13 Aug 2026 00:00:00 GMTA useful style guide resolves recurring editorial decisions quickly; it does not try to preserve every preference the team has ever discussed. Add a rule when writers repeatedly face the same decision and inconsistency actually matters.https://techwriters.org/articles/synthetic-examples-and-hallucinations/https://techwriters.org/articles/synthetic-examples-and-hallucinations/Thu, 13 Aug 2026 00:00:00 GMTGenerated examples can accelerate documentation work, but they must never be allowed to invent product behavior and then validate themselves. A code example is a factual claim about fields, values, order and behavior.https://techwriters.org/articles/technical-writer-2006/https://techwriters.org/articles/technical-writer-2006/Thu, 13 Aug 2026 00:00:00 GMTTools changed radically, but the durable core of technical writing is surprisingly recognizable: audience, evidence, structure, terminology and responsibility. In 2006 a technical writer could spend much more time in desktop publishing tools, office formats and manually maintained help systems.https://techwriters.org/articles/technical-writer-skills-matrix/https://techwriters.org/articles/technical-writer-skills-matrix/Thu, 13 Aug 2026 00:00:00 GMTA good matrix helps people grow and teams hire. A bad one turns vague personality traits into fake precision. Measure observable documentation capabilities and the complexity of problems a writer can own. Teams often build a skills matrix when hiring becomes inconsistent or promotion conversations become subjective.https://techwriters.org/articles/vale-style-linting/https://techwriters.org/articles/vale-style-linting/Thu, 13 Aug 2026 00:00:00 GMTStyle linting is valuable when it catches terminology drift, risky wording and repeatable editorial defects. Keep the rule set small, explainable and quiet enough that writers trust a failed check. A style linter can check thousands of sentences in seconds, which makes it tempting to encode every editorial preference.https://techwriters.org/articles/wcag-22-for-documentation/https://techwriters.org/articles/wcag-22-for-documentation/Thu, 13 Aug 2026 00:00:00 GMTAccessibility is not only a frontend task. Documentation authors control headings, link purpose, alternative text, tables, instructions and the structure that assistive technology depends on. A theme can provide good contrast and keyboard behavior, but authors still determine whether the content is understandable.https://techwriters.org/articles/when-manuals-shipped-on-cd/https://techwriters.org/articles/when-manuals-shipped-on-cd/Thu, 13 Aug 2026 00:00:00 GMTOffline documentation forced teams to think differently about versions, search, packaging and the cost of a mistake that could not be fixed after release. A physical publication deadline made content freeze, build verification and release coordination much more visible.https://techwriters.org/articles/working-with-subject-matter-experts/https://techwriters.org/articles/working-with-subject-matter-experts/Thu, 13 Aug 2026 00:00:00 GMTA review model that gets accurate answers from experts while protecting their time and keeping editorial responsibility with the writer. Ask experts for decisions and verification, not an undefined request for feedback.