Documentation Strategy

---

Definition

---

Types of Documentation

---

Architecture Decision Records

# ADR 001: Use PostgreSQL as Primary Database

## Status
Accepted

## Context
We need a database for our e-commerce platform. Options considered:
- PostgreSQL: Mature, ACID, good JSON support
- MongoDB: Flexible schema, horizontal scaling
- MySQL: Widely used, good performance

## Decision
We will use PostgreSQL as our primary database.

## Rationale
- Strong ACID guarantees for financial transactions
- JSON support for flexible product attributes
- Team familiarity
- Excellent tooling ecosystem
- Proven scalability for our projected load

## Consequences
### Positive
- Reliable transactions
- Rich query capabilities
- Strong community support

### Negative
- Less flexible schema than MongoDB
- Horizontal scaling more complex
- Requires DBA expertise for optimization

### Risks
- May need read replicas if read load grows significantly

## References
- PostgreSQL vs MongoDB comparison: [link]
- Load projections: [link]

---

Code Comments Best Practices

// BAD: Explaining WHAT (code already shows what)
// Increment i by 1
i++;

// GOOD: Explaining WHY
// Skip first element as it's the header row
for (int i = 1; i < rows.length; i++)

// BAD: Outdated comment
// Returns user's first name
public String getFullName() {  // Changed but comment wasn't
    return firstName + " " + lastName;
}

// GOOD: Documenting business rule
/**
 * Applies 15% discount for orders over $100.
 * Business rule: Marketing decision from Q3 2024 campaign.
 * See: JIRA-1234
 */
public Money calculateDiscount(Order order)

// GOOD: Warning about non-obvious behavior
/**
 * NOTE: This method has a side effect of updating the lastAccessed
 * timestamp. If you only need to check existence, use exists() instead.
 */
public Optional<User> findById(String id)

// GOOD: TODO with context
// TODO(TECH-456): Replace with proper caching layer
// This in-memory cache is temporary for MVP launch
// Must replace before scaling past 100 concurrent users
private Map<String, Session> sessionCache = new ConcurrentHashMap<>();

---

README Template

# Project Name

Brief description of what this project does.

## Quick Start

\`\`\`bash
# Prerequisites
node >= 18

# Install dependencies
npm install

# Run locally
npm run dev
\`\`\`

## Architecture

High-level overview with diagram.

## Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| DB_HOST  | Database host | localhost |
| API_KEY  | External API key | - |

## Development

### Running Tests
\`\`\`bash
npm test
npm run test:e2e
\`\`\`

### Code Style
We use ESLint and Prettier. Run `npm run lint` before committing.

## Deployment

Link to deployment documentation.

## Troubleshooting

### Common Issues

**Database connection fails**
Check that PostgreSQL is running and DB_HOST is correct.

## Contributing

See CONTRIBUTING.md

## License

MIT

---

Documentation as Code

# docs-as-code approach

# Generate API docs from code
openapi: 3.0.0
info:
  title: Order Service API
  version: 1.0.0

paths:
  /orders:
    post:
      summary: Create a new order
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
            example:
              customerId: "cust-123"
              items:
                - productId: "prod-456"
                  quantity: 2

# Benefits of docs-as-code:
# - Version controlled with code
# - Review process (PRs)
# - Automated generation
# - Always in sync with code
# - Can be tested (broken links, etc.)

# Tools:
# - Swagger/OpenAPI for APIs
# - Docusaurus/MkDocs for sites
# - Mermaid for diagrams in markdown
# - Javadoc/JSDoc for code docs

---

Keeping Docs Updated

---

Tips & Tricks

---