Technical Writing and Documentation Questions

Changelog entry (2025-11-22)

• Deprecated: GET /v1/users
• Replacement: GET /v2/users
• Deprecation announced: 2025-11-22
• Soft-deprecation (warnings sent): 2026-01-15
• Hard-deprecation (endpoint removed): 2026-06-30
  Notes: /v1 will continue to respond with a Deprecation-Warning header until removal. New clients should migrate to /v2 by 2026-01-15.

Migration note — key steps

1. Update base path to /v2/users.
2. Update request query params: v2 replaces "include_details" (boolean) with "fields" (comma-separated).
3. Update parsing for response: v2 nests profile under "profile" and uses "id" as string.
4. Run integration tests and check Deprecation-Warning header removal.

Example difference
Request v1:

GET /v1/users?include_details=true

Response v1:

[{ "id": 123, "name": "Alice", "email": "a@x.com" }]

Request v2:

GET /v2/users?fields=name,email,profile.picture

Response v2:

[{ "id": "123", "profile": { "name": "Alice", "email": "a@x.com", "picture": "..." } }]

Common migration error & troubleshooting tip
Symptom: 400 Bad Request when switching to v2 with include_details=true.
Cause: v2 rejects legacy param names.
Fix: Replace include_details with fields mapping (e.g., include_details=true → fields=name,email). If you still see 400, enable request logging and confirm query string encoding; some clients URL-encode commas—use percent-encoding or send fields as repeated params (fields=name&fields=email) which v2 accepts.

Summary
Add discount application to order totals by calling apply_discounts(total, user_id) from create_order.

What changed

• After computing line-item total, pass subtotal and user_id into apply_discounts(...) and use returned total in the order payload.
• Removes TODO placeholder for discounts.

Why

• Implements business requirement to apply per-user discounts (promotions, loyalty) at order creation time so totals are accurate for downstream billing and analytics.

QA / Testing steps

1. Unit tests:
   • Add tests for create_order with and without discounts mocked:
     • Mock apply_discounts to return lower total and assert order['total'] reflects it.
     • Test no-op case where apply_discounts returns identical subtotal.
2. Integration / manual:
   • Create orders for users with known discount profiles and verify totals in API response and DB.
   • Verify edge cases: zero-item orders, negative discounts (not allowed), very large totals.
3. Regression:
   • Run full test suite, smoke test checkout flow, and verify payment processing receives same total.
4. Logs:
   • Confirm no unexpected exceptions from apply_discounts; add sampling logs if needed.

Backward compatibility

• Function signature of create_order unchanged; callers receive same shape: {'order_id', 'total'}.
• Behavior change: totals may decrease for users with discounts. Downstream systems should expect discounted totals; this matches business intent.

Migration / Notes

• If apply_discounts pulls promotions from a new service or DB table, ensure that data is seeded prior to deployment.
• If discounts are time-bound, ensure clocks and TTLs are consistent between services.
• Consider a feature flag to roll out discounts gradually if risk is high.

Reviewer checklist

• Verify apply_discounts implementation and its error handling (fallback to subtotal on failure).
• Confirm unit tests cover discount/no-discount branches.
• Confirm no sensitive data is logged during discount computation.

Each service doc should be a single source of truth and follow a standard template so readers know where to find info quickly.

Recommended sections:

• Purpose & scope: business context, responsibilities, SLAs, and interactions.
• API: public endpoints/messages, sample requests/responses, versioning, auth, clients/SDKs.
• Data model: schema, relations, sensitive fields, retention, migration notes.
• Architecture & deployment: diagrams, runtime dependencies, infra (k8s, queues), scaling characteristics.
• Runbook & incidents: health checks, common failure modes, recovery steps, diagnostics, required dashboards/alerts.
• Ownership & contacts: primary owner, on-call rotation, repo links, related docs.
• Change log & compatibility guarantees.

Keeping docs current:

• Docs-as-code: store docs in the same repo or a closely linked repo versioned with code.
• PR checklist: require doc changes when related code changes; include a CI check that flags missing doc updates for public API/data model changes.
• Review gate: reviewers must verify docs as part of PR sign-off.
• Automation: generate API specs from code (OpenAPI), run schema diff tools, and surface stale-doc warnings from last-updated metadata.

Ensuring engineers read/use docs:

• Integrate docs into workflows: link docs in PR templates, issue templates, and the service README.
• Make docs discoverable: central index, searchable site, and crosslinks.
• Design reviews: require a docs walk-through for significant changes; include doc review on architecture review board agendas.
• Onboarding & training: embed short doc-reading tasks in onboarding checklist and pair new hires with owners to walk through the runbook.
• Keep docs concise and example-driven: include quickstart snippets, common debugging commands, and “if/then” recovery steps so engineers find immediate value.

These policies combine tooling, process, and incentives to keep documentation accurate and actually used.

Situation: My team struggled with stale or missing READMEs that slowed onboarding and increased support requests. I designed a README-driven development process to make docs a first-class artifact.

Process overview:

• Treat README as part of the “definition of done” for features and libs. Every new feature/repo change proposal begins with an updated README draft.

Ownership model:

• Repo-level primary owner: the feature/service tech lead or maintainer — responsible for accuracy.
• Collective responsibility: author of the PR updates docs; on-call/triage and UX writers are secondary reviewers for clarity.
• Quarterly doc steward rotation: one engineer per squad reviews cross-repo consistency and runs doc-improvement sprints.

PR checklist (enforced via template and CI gating):

• README updated or explicitly unchanged with justification
• Quickstart example present and runnable
• API/CLI usage documented
• Migration/upgrade notes (if applicable)
• Changelog entry (if behavior changed)
• Docs owner marked in README header

README templates (repo and feature):

• Header: name, one-line purpose, owner/contact, status badge
• Quickstart: 3–5 steps to run locally (copy-pastable)
• Usage: common commands / code snippets / config
• Examples: minimal working example(s)
• Troubleshooting & FAQ
• Testing: how to run examples/tests
• Compatibility & migrations
• Links: design doc, RFCs, related repos

CI checks:

• Linting: markdownlint + custom rules (no TODOs, required sections present)
• Link check: dead-link detector
• Example execution: run quickstart script in a lightweight container; expect exit code 0 and baseline output assertions
• Snippet verification: extract fenced code blocks labeled runnable and run in sandbox (or unit test harness)
• Badge generation: build/test/docs status updated automatically

Enforcement in sprint planning & PR review:

• Sprint planning: story templates include “Docs: README draft” task; acceptance criteria require README pass.
• Ticket definition: link README PR or path in description; docs owner assigned.
• PR reviewers required to sign off on docs checkbox; CI gates block merge until README lint & example tests pass.
• Review playbook: reviewers check clarity for first-time users, examples, and owner field. If failing, label “docs-needed” and request changes.
• Periodic metrics: track README coverage, CI doc-fail rate, and time-to-first-successful-example; review in retros.

Outcome: This makes documentation visible at planning time, enforces quality automatically, and distributes ownership while keeping PR flow efficient.

Situation: You're onboarding to a Node.js microservice repo and need to clone, run, test, lint, and make a tiny change locally. Follow these exact steps.

Clone repository and install

git clone git@github.com:your-org/my-microservice.git
cd my-microservice
# use npm or yarn depending on project
npm install
# OR
# yarn install

Expected output: dependency tree and "added X packages" (npm) or "success" (yarn).

Environment setup

# copy example env and edit values if needed
cp .env.example .env
# open .env and set e.g. PORT=3000, DB_URL=sqlite://:memory:

Expected: .env file present with configured PORT.

Start service (development)

# dev with hot reload (if provided)
npm run dev
# or production
npm start

Expected output:

• Dev: "Compiled successfully" and "Server listening on http://localhost:3000"
• Prod: "Server listening on port 3000"

Run unit tests and linters

# unit tests (Jest/Mocha)
npm test
# linting (ESLint)
npm run lint

Expected test output: summary like "X passed, 0 failed" and lint: "No problems" or list of issues.

Quick smoke test

# in another terminal
curl -i http://localhost:3000/health

Expected: HTTP/1.1 200 OK and JSON: {"status":"ok"} (or repo-specific payload).

Simple change-and-test exercise

1. Edit health endpoint to return message with your name:

• File: src/routes/health.js (or src/health.js)
• Change response from { status: 'ok' } to { status: 'ok', message: 'Hi, <YourName>' }

Example patch:

// src/routes/health.js
module.exports = (req, res) => {
  res.json({ status: 'ok', message: 'Hi, Alice' });
};

2. Run unit tests that cover health route (or add a small test)

npm test -- tests/health.test.js
# or run full suite
npm test

Expected: tests pass; new assertion should confirm message exists. Example test assertion (Jest):

expect(res.body.message).toBe('Hi, Alice');

3. Re-run smoke curl:

curl http://localhost:3000/health

Expected JSON contains message: {"status":"ok","message":"Hi, Alice"}

Notes & troubleshooting

• If ports conflict, change PORT in .env.
• If tests fail due to environment, run with CI-style env: NODE_ENV=test npm test.
• If linter errors appear, fix or run eslint --fix.
• Commit your change and push a branch:

git checkout -b feat/health-message
git add .
git commit -m "health: return personalized message"
git push -u origin feat/health-message