Technical Writing ও Documentation Excellence

Why Documentation?

• Onboarding — new dev productive দ্রুত
• Knowledge preservation (people leave)
• Reduce support burden
• Alignment across team
• Future-you will thank you

Diátaxis Framework ⭐

Type	Audience	Goal
Tutorial	Beginner	Learning
How-to Guide	User with task	Solve problem
Reference	User needs detail	Lookup
Explanation	Anyone	Understanding concept

Great README Structure

# Project Name
One-line description

[![CI](badge)] [![Coverage](badge)]

## Features
- Feature 1
- Feature 2

## Quick Start
\`\`\`bash
git clone ...
npm install
npm run dev
\`\`\`

## Configuration
ENV VARS table

## Architecture
High-level diagram

## Development
Setup, scripts, conventions

## Deployment
CI/CD, env setup

## API Documentation
Link to Swagger

## Contributing
PR process, code style

## License
MIT

API Documentation ⭐

OpenAPI / Swagger

openapi: 3.0.0
info: { title: Users API, version: 1.0.0 }
paths:
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema: { $ref: '#/components/schemas/User' }
        '404':
          description: Not found

Tools: Swagger UI, Redoc, Postman, Insomnia।

Code Comments

❌ // increment counter
counter++;

✅ // Retry up to 3 times with exponential backoff
//    to handle transient network failures
for (int i = 0; i < 3; i++) { ... }

✅ // WARNING: This must run before indexing,
//    otherwise dangling pointers will cause crashes.

// Document WHY, not WHAT (code shows what)

JSDoc / XML Doc / DocStrings

/**
 * Calculate total with tax
 * @param {number} subtotal - Pre-tax amount
 * @param {number} rate - Tax rate (0-1)
 * @returns {number} Total with tax
 * @throws {Error} If rate < 0 or > 1
 * @example
 *   calculateTotal(100, 0.08) // 108
 */
function calculateTotal(subtotal, rate) { ... }

Runbook ⭐

Operational playbook — incident-এ follow।

# Runbook: Database High CPU Alert

## Symptoms
- CPU > 90% for 5 minutes
- Slow query alerts firing

## Diagnosis
1. Check pg_stat_activity:
   SELECT * FROM pg_stat_activity ORDER BY query_start;
2. Identify long-running queries
3. Check current load vs baseline

## Mitigation
- Kill runaway queries:
  SELECT pg_cancel_backend(pid);
- Scale up if traffic spike
- Enable read replica
- Check recent deployments (rollback if suspect)

## Escalation
- Page DBA if not resolved in 15 min
- Slack: #database-oncall

## Post-incident
- Write postmortem
- Add slow query alert improvements

Architecture Decision Record (ADR)

# ADR 0007: Use PostgreSQL

## Status: Accepted (2024-03-15)

## Context
Multi-tenant SaaS, JSON columns needed.

## Decision
PostgreSQL 15.

## Consequences
+ Strong jsonb support
+ Mature ecosystem
- Team less familiar (training needed)

## Alternatives considered
- MySQL: weaker JSON
- MongoDB: transaction limited

Tutorial Writing Tips

• Single clear outcome
• Prerequisites upfront
• Step-by-step, testable
• Show expected output
• Troubleshooting section
• Next steps link

Good Writing Principles

• Know your audience (skill level)
• Active voice ("Click Submit" not "Submit should be clicked")
• Short sentences
• Scannable (headings, bullets, bold)
• Examples > abstract
• Screenshots for UI
• Diagrams for architecture
• Keep up-to-date (doc drift is real)

Docs-as-Code ⭐

repo/
├── docs/
│   ├── getting-started.md
│   ├── architecture/
│   │   ├── overview.md
│   │   └── adr/
│   ├── api/
│   │   └── openapi.yaml
│   ├── runbooks/
│   └── tutorials/
└── mkdocs.yml
# Docs in git, review in PR, deploy automatic

Tools

MkDocs + Material (popular), Docusaurus, GitBook, Read the Docs, Notion, Confluence।

Diagrams

• Mermaid — markdown, git-friendly
• PlantUML — text-based UML
• Draw.io / diagrams.net — free
• Lucidchart — enterprise
• Excalidraw — sketchy look
• Structurizr — C4 model