A Short Guide to Technical Documentation

Purpose: Provide clear backend requirements for a simple contact app that stores a person’s name and phone number. This example demonstrates how to write minimal, precise technical documentation suitable for developers to start building the backend.

1. Minimal Technical Requirements

Data to store:

• name (string, required)
• phone_number (string, required, unique)
• Database: Relational database (MySQL)
• API input/output format: JSON

Validation and error handling: Required for all fields; handle duplicates, empty values, and malformed input

2. Database Schema (DDL)

CREATE TABLE contacts (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    phone_number VARCHAR(20) NOT NULL UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Edge Cases to Consider:

• name cannot be empty or null
• phone_number must be unique, properly formatted (digits only, optional leading +)
• Maximum lengths enforced to prevent overflow
• Concurrent inserts must respect uniqueness

3. SQL Queries

Insert a New Contact:

INSERT INTO contacts (name, phone_number)
VALUES ('John Doe', '+1234567890');

Query to Retrieve All Contacts:

SELECT id, name, phone_number, created_at
FROM contacts
ORDER BY created_at DESC;

Query to Find Contact by Phone Number:

SELECT id, name, phone_number
FROM contacts
WHERE phone_number = '+1234567890';

4. API Contract (JSON)

Request: Create Contact

{
  "name": "John Doe",
  "phone_number": "+1234567890"
}

Successful Response:

{
  "id": 1,
  "name": "John Doe",
  "phone_number": "+1234567890",
  "created_at": "2026-03-12T12:00:00Z"
}

Error Responses:

5. Validation Rules

• Name: 1–100 characters, cannot be empty
• Phone Number: 7–20 digits, optional leading +, must be unique
• Database: Enforce uniqueness constraint at table level
• API: Validate JSON input before insert; respond with clear error messages

Conclusion:

This documentation provides all minimal technical requirements for a backend developer to start building a contact app API. By clearly specifying fields, database schema, queries, JSON contracts, and validation rules, technical writers ensure developers can implement the API reliably and consistently.