Technical Writing and Documentation 101: Documentation Lifecycle (Plan, Draft, Review, Publish, Maintain)

Documentation Lifecycle (Plan, Draft, Review, Publish, Maintain)

Documentation Lifecycle: A Practical Study Guide

(Plan → Draft → Review → Publish → Maintain)

What This Is

The documentation lifecycle is the end-to-end process of creating, updating, and retiring technical content—from planning a new API reference to archiving outdated CLI commands. A well-managed lifecycle ensures docs stay accurate, useful, and aligned with the product, which directly impacts user adoption and developer productivity.

Real-world example:
Stripe’s API reference starts with a product spec (Plan), gets drafted in Markdown (Draft), is peer-reviewed by engineers (Review), auto-published via a docs-as-code pipeline (Publish), and updated via GitHub PRs when the API changes (Maintain). Without this cycle, users might struggle to integrate payments, leading to support tickets and churn.

Key Terms & Tools

• Documentation Plan: A lightweight roadmap (often a Google Doc or Notion page) outlining scope, audience, tools, and timelines. Example: "We’ll document the new /payments endpoint for merchants (audience: backend devs) using OpenAPI + Redoc, due in 2 sprints."
• Docs-as-Code: Treating docs like software—stored in Git (e.g., GitHub/GitLab), written in Markdown/AsciiDoc, built with static site generators (e.g., Sphinx, Docusaurus), and reviewed via pull requests (PRs).
• OpenAPI (Swagger): A machine-readable spec (YAML/JSON) for REST APIs. Tools like Swagger UI or Redoc auto-generate interactive docs from the spec.
• Static Site Generator (SSG): A tool (e.g., Hugo, MkDocs) that converts Markdown files into a website. Why? Faster than CMSes, version-controlled, and deployable via CI/CD.
• CI/CD for Docs: Automating doc builds/deployments using tools like GitHub Actions or GitLab CI. Example: A PR merge triggers a build that deploys docs to docs.yourproduct.com.
• DITA (Darwin Information Typing Architecture): An XML-based standard for modular, reusable docs (common in enterprise). Tool: Oxygen XML Editor.
• Markdown: A lightweight markup language for formatting text (e.g., # Heading, bold). Pro tip: Use CommonMark for consistency.
• API Reference: A structured doc listing endpoints, parameters, responses, and examples (e.g., Stripe’s API). Format: OpenAPI + auto-generated UI.
• Conceptual Docs: High-level explanations of how a system works (e.g., "How OAuth 2.0 Works in Our App"). Not a tutorial or reference.
• Tutorial: A step-by-step guide that teaches a concept by building something (e.g., "Build a Weather App with Our API"). Key: Hands-on, with code snippets and expected outputs.
• How-To Guide: A problem-focused doc (e.g., "How to Reset Your API Key"). Key: Solves a specific task, not a broad concept.
• Diátaxis Framework: A methodology for organizing docs into 4 types: Tutorials, How-To Guides, Explanations, and Reference. Tool: Diátaxis website.

Step-by-Step / Process Flow

1. Plan: Define Scope and Audience

Actions:
- Read the product spec or RFC (e.g., "New /subscriptions endpoint for SaaS billing").
- Identify the audience (e.g., "Backend devs at startups" vs. "Non-technical admins").
- Choose the doc type (e.g., API reference, tutorial, or how-to guide).
- Pick tools/formats (e.g., OpenAPI for API docs, Markdown for guides).
- Create a doc plan (1-pager with scope, timeline, and stakeholders).

Example:

Doc Plan for /subscriptions Endpoint - Audience: Backend engineers integrating recurring payments.
- Doc Type: API reference + tutorial ("Set Up a Subscription").
- Tools: OpenAPI (YAML) + Redoc for reference; Markdown + Docusaurus for tutorial.
- Timeline: Draft by Sprint 5, review by Sprint 6, publish with v2.1 release.

2. Draft: Write and Test

Actions:
- For API docs:
- Read the OpenAPI spec (or write one if missing).
- Test endpoints in Postman or curl.
- Draft descriptions for each endpoint, parameter, and response.
- Add code examples (e.g., curl, Python, JavaScript).
- Pro tip: Use OpenAPI Generator to auto-generate SDK examples.
- For guides/tutorials:
- Follow the Diátaxis framework to structure content.
- Write in Markdown (use VS Code with Markdown All in One extension).
- Test all code snippets in a sandbox environment.
- For CLI tools:
- Document commands with --help flags and examples.
- Use CLI documentation tools like Docopt or Cobra.

Example (OpenAPI snippet):

paths:
  /subscriptions:
    post:
      summary: Create a subscription
      description: |
        Subscribes a customer to a plan. Returns a subscription object.
      parameters:
        - name: customer_id
          in: query
          required: true
          schema:
            type: string
          example: "cus_123abc"
      responses:
        "201":
          description: Subscription created
          content:
            application/json:
              example:
                id: "sub_456def"
                status: "active"

3. Review: Validate Accuracy and Clarity

Actions:
- Technical review: Share with engineers via PR (e.g., GitHub/GitLab). Ask: "Does this match the current API behavior?" - Peer review: Have another writer check for clarity, grammar, and consistency (use Vale for style linting).
- User review (optional): Test with a small group of target users (e.g., via UserTesting).
- Tools:
- Vale: Lint docs against a style guide (e.g., Google’s or Microsoft’s).
- Reviewable: For GitHub PR reviews.
- Netlify Preview: Deploy a staging site for visual review.

Example PR comment:

"The customer_id parameter is marked as required, but the API allows email as an alternative. Should we document both? Also, the example uses cus_123abc, but our IDs are now 16 chars (e.g., cus_123abc456def78)."

4. Publish: Deploy and Announce

Actions:
- Merge the PR to the main branch (triggers CI/CD pipeline).
- Verify the build (e.g., check Netlify/Cloudflare Pages for errors).
- Update navigation (e.g., add a link to the new API endpoint in the sidebar).
- Announce the docs:
- Slack/email to internal teams.
- Changelog entry (e.g., "Added /subscriptions endpoint docs").
- Social media (e.g., "New tutorial: Build a SaaS billing system with our API").
- Tools:
- GitHub Pages: Free hosting for docs.
- Read the Docs: Hosts Sphinx/MkDocs projects.
- Algolia DocSearch: Add search to your docs.

Example CI/CD snippet (GitHub Actions):

name: Deploy Docs
on:
  push:
    branches: [ main ]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v3
      - run: npm install && npm run build
      - run: npm run deploy

5. Maintain: Keep Docs in Sync

Actions:
- Monitor feedback: Watch GitHub issues, Slack, or Disqus comments for user questions.
- Update with code changes: When the API/CLI changes, create a PR to update docs before the release.
- Deprecate old docs: Archive or redirect outdated content (e.g., "This endpoint is deprecated; use /v2/subscriptions instead").
- Automate checks:
- Snyk: Scan for vulnerable dependencies in docs-as-code repos.
- Broken Link Checker: Find dead links.
- Tools:
- Renovate: Auto-update dependencies in docs repos.
- GitHub Dependabot: Alerts for outdated tools.

Example maintenance PR:

"Update /subscriptions docs for v2.1 - Added trial_period_days parameter.
- Updated examples to use new ID format.
- Deprecated plan_id in favor of price_id (see migration guide)."*

Common Mistakes

Tech Writing Interview / Portfolio Tips

What Hiring Managers Look For

1. Process over polish: Show your workflow (e.g., "Here’s how I planned, drafted, and reviewed this API doc"). Include screenshots of PRs, Trello boards, or CI/CD pipelines.
2. Tool proficiency: Highlight experience with:
3. Docs-as-code: Git, Markdown, static site generators.
4. API docs: OpenAPI, Postman, Swagger UI/Redoc.
5. Collaboration: GitHub/GitLab PRs, Slack, Jira.
6. Audience awareness: Distinguish between:
7. Tutorial (teaches by building) vs. How-To Guide (solves a specific problem).
8. Reference (structured, e.g., API endpoint list) vs. Conceptual (explains "why").
9. Portfolio examples:
10. API docs: Include an OpenAPI spec + auto-generated UI (e.g., Redoc demo).
11. Tutorial: Show a step-by-step guide with code snippets (e.g., "Build a Slack bot with our API").
12. CLI docs: Document a command with --help flags and examples.

Tricky Distinctions

• Swagger UI vs. Redoc:
• Swagger UI: Interactive (try endpoints in the browser), but cluttered.
• Redoc: Cleaner, better for reference docs, but not interactive.
• DITA vs. Docs-as-Code:
• DITA: XML-based, enterprise-focused, steep learning curve.
• Docs-as-Code: Git + Markdown, agile-friendly, easier for devs to contribute.

Quick Check Questions

1. Scenario: A developer complains that the API docs are outdated. How would you ensure docs stay in sync with code?
2. Answer: Implement docs-as-code with CI/CD checks (e.g., fail builds if OpenAPI spec doesn’t match the code) and schedule regular audits.

3. Why? Automation reduces human error, and audits catch drift.

4. Scenario: Your team wants to document a new CLI tool. What’s the first step?

5. Answer: Plan the doc type (e.g., reference for commands, tutorial for setup) and test the CLI to document real behavior (not just the spec).

6. Why? CLI behavior often differs from design docs; testing ensures accuracy.

7. Scenario: A stakeholder asks for a "comprehensive guide" to your product. How do you scope this?

8. Answer: Use the Diátaxis framework to split the guide into tutorials (learning), how-to guides (tasks), explanations (concepts), and reference (API/CLI).
9. Why? "Comprehensive" is vague; Diátaxis provides a clear structure.

Last-Minute Cram Sheet

1. Docs-as-Code: Git + Markdown + SSG (e.g., Docusaurus) + CI/CD.
2. OpenAPI: YAML/JSON spec for APIs; use Swagger Editor to validate.
3. Diátaxis: Tutorials (learn), How-To Guides (solve), Explanations (understand), Reference (look up).
4. Markdown quirks:
5. bold (not <b>bold</b>).
6. Code blocks: ```python (language matters for syntax highlighting).
7. ⚠️ Tutorial ≠ How-To Guide: Tutorials teach concepts by building; how-to guides solve specific problems.
8. CI/CD for docs: GitHub Actions, Netlify, or Read the Docs.
9. SEO for docs: Descriptive titles, meta descriptions, and keywords (e.g., "Stripe API subscription tutorial").
10. Deprecation: Always redirect or archive old docs (e.g., 301 redirect in .htaccess).
11. OpenAPI versions:
12. 2.0 (Swagger): Older, simpler.
13. 3.x: Supports callbacks, links, and better examples.
14. ⚠️ "Just write it later" trap: Docs should be written before code ships (or in parallel). Delaying leads to outdated docs.