Technical Writing Prompt Templates

# Setting Up Two-Factor Authentication

Two-factor authentication (2FA) adds an extra layer of security to your account by requiring a code from your phone in addition to your password.

**Time required:** 5 minutes

**What you'll need:**
- Your smartphone
- An authenticator app (Google Authenticator, Authy, or Microsoft Authenticator)

---

## Step 1: Open Security Settings

1. Click your profile picture in the top-right corner
2. Select **Settings** from the dropdown menu
3. Click **Security** in the left sidebar

[Screenshot placeholder: Settings menu with Security highlighted]

## Step 2: Enable Two-Factor Authentication

1. Find the **Two-Factor Authentication** section
2. Click the **Enable 2FA** button
3. You'll see a QR code on screen, keep this window open

[Screenshot placeholder: QR code screen]

## Step 3: Connect Your Authenticator App

1. Open your authenticator app on your phone
2. Tap the **+** button to add a new account
3. Select **Scan QR Code**
4. Point your phone camera at the QR code on screen
5. Your authenticator app will display a 6-digit code

## Step 4: Verify Setup

1. Enter the 6-digit code from your authenticator app into the verification field
2. Click **Verify**
3. You'll see a confirmation message if successful

## Step 5: Save Your Backup Codes

**Important:** Don't skip this step.

1. After verification, you'll see 10 backup codes
2. Click **Download Codes** to save them as a file
3. Store these codes somewhere safe (password manager, printed copy in secure location)
4. Each code can only be used once

[Screenshot placeholder: Backup codes screen with download button]

---

## Troubleshooting

### The code from my authenticator app doesn't work

- Make sure you're entering the code before it expires (codes change every 30 seconds)
- Check that your phone's time is set automatically (Settings > Time > Set Automatically)
- Try scanning the QR code again, you may have scanned it incorrectly

### I lost my phone / got a new phone

- Use one of your backup codes to log in
- After logging in, disable 2FA and set it up again with your new phone
- If you don't have backup codes, contact support@[company].com

### I can't scan the QR code

- Click **Can't scan?** below the QR code for a manual setup key
- Enter this key manually in your authenticator app instead of scanning

---

**Need help?** Contact support at support@[company].com

# Create Invoice

Creates a new invoice for an existing customer.

```
POST /api/v1/invoices
```

## Authentication

Requires a valid API key passed as a Bearer token.

```
Authorization: Bearer your_api_key_here
```

## Request Body

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| customer_id | string | Yes | The unique identifier of the customer |
| line_items | array | Yes | Array of invoice line items (see below) |
| due_date | string | No | Payment due date in ISO 8601 format (defaults to 30 days from creation) |
| notes | string | No | Additional notes to appear on the invoice |

### Line Item Object

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| description | string | Yes | Description of the product or service |
| quantity | integer | Yes | Quantity (must be at least 1) |
| unit_price | integer | Yes | Price per unit in cents |

## Example Request

```bash
curl -X POST https://api.example.com/api/v1/invoices \
 -H "Authorization: Bearer your_api_key_here" \
 -H "Content-Type: application/json" \
 -d '{
 "customer_id": "cus_abc123",
 "line_items": [
 {
 "description": "Website Design",
 "quantity": 1,
 "unit_price": 250000
 },
 {
 "description": "Hosting (Monthly)",
 "quantity": 12,
 "unit_price": 2999
 }
 ],
 "due_date": "2024-02-15",
 "notes": "Thank you for your business!"
 }'
```

## Response

Returns the created invoice object.

```json
{
 "id": "inv_xyz789",
 "customer_id": "cus_abc123",
 "status": "draft",
 "line_items": [
 {
 "description": "Website Design",
 "quantity": 1,
 "unit_price": 250000,
 "total": 250000
 },
 {
 "description": "Hosting (Monthly)",
 "quantity": 12,
 "unit_price": 2999,
 "total": 35988
 }
 ],
 "subtotal": 285988,
 "total": 285988,
 "due_date": "2024-02-15",
 "notes": "Thank you for your business!",
 "created_at": "2024-01-15T10:30:00Z"
}
```

## Errors

| Status Code | Error Type | Description |
|-------------|------------|-------------|
| 400 | validation_error | Invalid request body. Check the `errors` array in the response for specific field errors. |
| 401 | authentication_error | Invalid or missing API key. |
| 404 | not_found | The specified customer_id does not exist. |
| 429 | rate_limit_exceeded | Too many requests. Wait before retrying. |

### Example Error Response

```json
{
 "error": {
 "type": "validation_error",
 "message": "Invalid request body",
 "errors": [
 {
 "field": "line_items[0].unit_price",
 "message": "Must be a positive integer"
 }
 ]
 }
}
```

## Rate Limits

This endpoint is limited to 100 requests per minute. If you exceed this limit, you'll receive a 429 response. The `Retry-After` header indicates how many seconds to wait before retrying.

# Technical Specification: Email Notification System

**Author:** [Name] 
**Status:** Draft 
**Last Updated:** January 15, 2024 
**Reviewers:** [Engineering Lead], [Product Manager]

---

## 1. Overview

### Problem Statement

Users currently have no way to know about important events (new comments, approval requests, etc.) without actively checking the application. This leads to missed deadlines, delayed responses, and user frustration.

### Proposed Solution

Implement an email notification system that sends timely, relevant emails when events occur, with user-configurable preferences.

### Scope

**In Scope:**
- Email delivery infrastructure
- User notification preferences
- Five notification types (see Section 3)
- Unsubscribe functionality
- Email templates

**Out of Scope:**
- Push notifications (future phase)
- SMS notifications (future phase)
- Notification center in-app (separate spec)

---

## 2. Requirements

### Functional Requirements

| ID | Requirement | Priority |
|----|-------------|----------|
| FR-1 | System sends emails within 5 minutes of triggering event | High |
| FR-2 | Users can enable/disable each notification type | High |
| FR-3 | All emails include one-click unsubscribe link | High |
| FR-4 | System respects user timezone for delivery | Medium |
| FR-5 | Digest option to batch notifications (daily/weekly) | Medium |

### Non-Functional Requirements

| ID | Requirement | Target |
|----|-------------|--------|
| NFR-1 | Handle 10,000+ emails/day | Capacity |
| NFR-2 | Email delivery rate >98% | Reliability |
| NFR-3 | GDPR compliant (consent, data access, deletion) | Compliance |
| NFR-4 | Email send latency <30 seconds | Performance |

---

## 3. Notification Types (Phase 1)

| Type | Trigger | Default |
|------|---------|--------|
| New Comment | Someone comments on user's item | On |
| Approval Request | User is assigned as approver | On |
| Approval Decision | User's submission is approved/rejected | On |
| Weekly Summary | Every Monday 9am user's timezone | On |
| Mention | User is @mentioned | On |

---

## 4. Technical Design

### Architecture

```
[Application] → [Event Bus] → [Notification Worker] → [Email Queue] → [SendGrid] → [User]
 ↓
 [Preferences DB]
```

### Key Components

**Event Bus:** Application publishes events to a Redis-backed queue. Events include type, actor, subject, and relevant entity IDs.

**Notification Worker:** Background process that:
1. Consumes events from queue
2. Checks user notification preferences
3. Determines recipients
4. Renders email templates
5. Queues for delivery

**Email Queue:** Separate queue for email delivery with retry logic. Allows us to handle SendGrid rate limits and temporary failures.

### Decision: Why Queue-Based Architecture

We considered synchronous email sending but rejected it because:
- Blocks user actions while email sends
- No retry capability if email provider is down
- Can't handle burst traffic (e.g. bulk operations)

The queue adds complexity but provides reliability and scalability.

### Decision: Why SendGrid

Evaluated: SendGrid, Amazon SES, Mailgun

Chose SendGrid because:
- Best deliverability reputation for transactional email
- Solid webhook system for tracking bounces/complaints
- Team has prior experience
- Cost is comparable (~$20/month at our volume)

---

## 5. Database Schema

```sql
CREATE TABLE notification_preferences (
 id UUID PRIMARY KEY,
 user_id UUID REFERENCES users(id),
 notification_type VARCHAR(50),
 enabled BOOLEAN DEFAULT true,
 digest_frequency VARCHAR(20) DEFAULT 'immediate',
 created_at TIMESTAMP,
 updated_at TIMESTAMP,
 UNIQUE(user_id, notification_type)
);

CREATE TABLE email_logs (
 id UUID PRIMARY KEY,
 user_id UUID REFERENCES users(id),
 notification_type VARCHAR(50),
 email_provider_id VARCHAR(100),
 status VARCHAR(20),
 sent_at TIMESTAMP,
 delivered_at TIMESTAMP,
 opened_at TIMESTAMP
);
```

---

## 6. Edge Cases

| Scenario | Handling |
|----------|----------|
| User has no email address | Skip notification, log warning |
| User has unsubscribed via email link | Respect preference, don't send |
| Same event triggers multiple notifications | Deduplicate within 5-minute window |
| Email bounces | Mark email as invalid after 3 bounces, notify user in-app |
| User deletes account | Delete preferences, stop all pending emails |

---

## 7. Open Questions

1. **Digest batching logic:** If user has 50 comments in a day, do we group by item or send chronologically?
2. **Email frequency limits:** Should we cap at N emails per hour per user to prevent spam perception?
3. **Template ownership:** Who maintains and updates email copy, Engineering or Marketing?

---

## 8. Timeline

| Milestone | Target Date |
|-----------|-------------|
| Spec approval | Jan 22 |
| Infrastructure complete | Feb 5 |
| First notification type live | Feb 12 |
| All 5 types complete | Feb 26 |
| Preference UI complete | March 4 |

### 1. Invalid Login Credentials

**Message:** "The email or password you entered doesn't match our records."

**Subtext:** "Check for typos and make sure Caps Lock is off."

**Action:** [Try Again] [Forgot Password?]

*Rationale: Don't specify whether email or password was wrong (security). Provide common solutions and clear next steps.*

---

### 2. Session Timeout

**Message:** "Your session has expired for your security."

**Subtext:** "After 10 minutes of inactivity, we automatically sign you out to protect your account."

**Action:** [Sign In Again]

*Rationale: Explain WHY it happened so users don't think something broke. Frame as protection, not inconvenience.*

---

### 3. Transfer Amount Exceeds Daily Limit

**Message:** "This transfer exceeds your daily limit of $2,500."

**Subtext:** "You can transfer up to $1,847 more today. Your limit resets at midnight."

**Action:** [Edit Amount] [Learn About Limits]

*Rationale: Tell them exactly what the limit is and how much room they have. Give them a path forward.*

---

### 4. Recipient Account Not Found

**Message:** "We couldn't find an account with that information."

**Subtext:** "Double-check the account number and routing number with your recipient."

**Action:** [Edit Recipient Details]

*Rationale: Don't say 'account doesn't exist' (might just be a typo). Suggest the most likely solution.*

---

### 5. Maintenance Window / Planned Downtime

**Message:** "We're doing some scheduled maintenance right now."

**Subtext:** "We expect to be back by 6:00 AM EST. We're sorry for any inconvenience."

**Action:** [Check Status Page]

*Rationale: Be specific about when they can return. Acknowledge the inconvenience. Give them a way to get updates.*

---

### General Principles Applied:

1. **Never blame the user:** "doesn't match our records" not "you entered the wrong password"
2. **Be specific:** Include actual numbers (daily limit, time estimates) when possible
3. **Provide next steps:** Every error should have a clear action the user can take
4. **Match the severity:** Security timeouts should feel protective; typos should feel fixable

# TaskQueue

[![npm version](https://badge.fury.io/js/taskqueue.svg)](https://badge.fury.io/js/taskqueue)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)

A lightweight, reliable job queue for Node.js applications, powered by Redis.

## Table of Contents

- [Features](#features)
- [Quick Start](#quick-start)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Dashboard](#dashboard)
- [API Reference](#api-reference)
- [Contributing](#contributing)
- [License](#license)

## Features

- **Reliable Processing** - Jobs are persisted in Redis and survive restarts
- **Automatic Retries** - Exponential backoff with configurable attempts
- **Job Prioritization** - Process urgent jobs first
- **Scheduling** - Run jobs at specific times or on cron schedules
- **Dashboard** - Built-in web UI for monitoring and management
- **TypeScript** - Full type definitions included

## Quick Start

```bash
# Install the package
npm install taskqueue

# Make sure Redis is running
redis-server
```

```typescript
import { Queue, Worker } from 'taskqueue';

// Create a queue
const emailQueue = new Queue('emails');

// Add a job
await emailQueue.add('send-welcome', {
 to: 'user@example.com',
 template: 'welcome'
});

// Process jobs
const worker = new Worker('emails', async (job) => {
 await sendEmail(job.data.to, job.data.template);
});
```

## Installation

### Requirements

- Node.js 18 or higher
- Redis 6 or higher

### Install via npm

```bash
npm install taskqueue
```

### Install via yarn

```bash
yarn add taskqueue
```

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `REDIS_URL` | Redis connection string | `redis://localhost:6379` |
| `TASKQUEUE_CONCURRENCY` | Jobs processed simultaneously | `5` |
| `TASKQUEUE_MAX_RETRIES` | Retry attempts before failing | `3` |

### Programmatic Configuration

```typescript
const queue = new Queue('emails', {
 connection: {
 host: 'localhost',
 port: 6379,
 password: 'optional'
 },
 defaultJobOptions: {
 attempts: 5,
 backoff: {
 type: 'exponential',
 delay: 1000
 }
 }
});
```

## Usage

### Adding Jobs

```typescript
// Simple job
await queue.add('job-name', { data: 'here' });

// With options
await queue.add('job-name', { data: 'here' }, {
 priority: 1, // Higher = processed first
 delay: 5000, // Wait 5 seconds before processing
 attempts: 10 // Retry up to 10 times
});

// Scheduled job
await queue.add('job-name', { data: 'here' }, {
 repeat: { cron: '0 9 * * *' } // Every day at 9am
});
```

### Processing Jobs

```typescript
const worker = new Worker('emails', async (job) => {
 console.log(`Processing ${job.name} with data:`, job.data);
 
 // Do your work here
 await sendEmail(job.data);
 
 // Return a result (optional)
 return { sent: true };
});

// Handle events
worker.on('completed', (job, result) => {
 console.log(`Job ${job.id} completed with result:`, result);
});

worker.on('failed', (job, error) => {
 console.error(`Job ${job.id} failed:`, error.message);
});
```

## Dashboard

TaskQueue includes a built-in dashboard for monitoring your queues.

```typescript
import { Dashboard } from 'taskqueue/dashboard';

const dashboard = new Dashboard({
 queues: [emailQueue, reportQueue],
 port: 3000
});

dashboard.listen();
// Dashboard available at http://localhost:3000
```

## API Reference

Full API documentation is available at [docs.taskqueue.dev](https://docs.taskqueue.dev).

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

MIT License - see [LICENSE](LICENSE) for details.