A Short Guide to Technical Documentation
by Arif Ikhsanudin, Backend Developer
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:
| Condition | HTTP Status | Response |
|---|---|---|
| Missing required field | 422 Unprocessable Entity | { "error": "Field 'name' is required" } |
| Invalid phone format | 422 Unprocessable Entity | { "error": "Phone number must contain only digits and optional leading '+'" } |
| Duplicate phone number | 400 Bad Request | { "error": "Phone number already exists" } |
| Database error | 500 Internal Server Error | { "error": "Internal server error" } |
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.