Technical Writing Fundamentals

Lesson preview

Syllabus

1. Lesson 1

   Diagnosing Documentation Anti-Patterns

   Diagnose technical documentation anti-patterns by identifying feature dumps, unstructured walls of text, and missing user context

2. Lesson 2

   Applying the Diátaxis Framework

   Apply the Diátaxis framework to map documentation types to reader psychology across tutorials, how-to guides, reference, and explanation

3. Lesson 3

   Implementing Docs-as-Code Workflows

   Adopt the Docs-as-Code workflow by managing markdown files, version control, and CI/CD pipelines alongside source code

4. Lesson 4

   Writing Clear Prose and Plain Language

   Enforce clear prose and plain language by eliminating jargon, passive voice, and redundant filler words in engineering docs

5. Lesson 5

   Designing Effective Repository READMEs

   Structure a high-impact repository README as a landing page that answers visitor questions within thirty seconds

6. Lesson 6

   Crafting Quickstart and Installation Guides

   Write actionable installation and quickstart guides featuring minimal working snippets for zero-to-sixty setup

7. Lesson 7

   Writing Beginner-Facing Tutorials

   Author practical step-by-step tutorials that build confidence for beginners through safe, predictable hands-on paths

8. Lesson 8

   Creating Task-Oriented How-To Guides

   Design task-oriented how-to guides that address specific real-world problems for competent users

9. Lesson 9

   Explaining Conceptual Architecture

   Structure comprehensive conceptual explanations detailing background context and design rationale without code clutter

10. Lesson 10

    Drafting Technical Reference Manuals

    Define precise technical reference manuals documenting system machinery, parameters, and return types systematically

11. Lesson 11

    Designing Developer-First API Documentation

    Design developer-first API documentation prioritizing DX, code blocks, and concrete error payloads

12. Lesson 12

    Authoring OpenAPI and Swagger Specifications

    Author OpenAPI and Swagger specifications by writing machine-readable YAML and JSON schemas for automatic UI generation

13. Lesson 13

    Documenting HTTP Request and Response Semantics

    Document HTTP request and response semantics detailing methods, required headers, and sample JSON payloads accurately

14. Lesson 14

    Documenting Error Handling and Troubleshooting

    Implement robust error handling documentation explaining non-2xx status codes, error codes, and troubleshooting steps

15. Lesson 15

    Managing API Versioning and Deprecation

    Manage API versioning and deprecation transparently to communicate breaking changes without alienating consumers

16. Lesson 16

    Creating Architecture Decision Records (ADRs)

    Capture technical design choices in Architecture Decision Records by recording context, decisions, and trade-offs

17. Lesson 17

    Writing Structured ADR Context and Consequences

    Write structured ADR context and consequences detailing constraints, forces, and downstream impacts of architectural choices

18. Lesson 18

    Maintaining and Indexing an ADR Log

    Maintain an ADR repository log linking decisions to codebase evolution and resolving architectural drift

19. Lesson 19

    Automating Documentation Linting and Testing

    Lint and test technical documentation automatically by configuring prose linters, link checkers, and markdown validators

20. Lesson 20

    Optimizing Documentation for AI and RAG Systems

    Optimize documentation for AI and RAG systems by structuring markdown with semantic headings and clean chunking for LLM coding assistants

21. Lesson 21

    Auditing and Refactoring Legacy Documentation

    Audit and refactor legacy engineering documentation to transform stale, disorganized wikis into structured libraries