Technical Documentation
March 16, 2026 ยท View on GitHub
Markdown Viewer excels at creating technical documentation with code, diagrams, and formulas. Here's how to use it effectively for tech docs.
Why Use Markdown for Tech Docs?
| Advantage | Description |
|---|---|
| Version Control | Track changes in Git |
| Plain Text | Edit with any tool |
| Portable | Works everywhere |
| Fast | No loading times |
| Collaborative | Easy merge/diff |
Perfect for Architecture Docs
System Architecture
## System Architecture
Our platform uses a microservices architecture:
```mermaid
graph TB
subgraph "Client Layer"
Web[Web App]
Mobile[Mobile App]
API[API Clients]
end
subgraph "API Gateway"
GW[Kong Gateway]
Auth[Auth Service]
end
subgraph "Services"
Users[User Service]
Products[Product Service]
Orders[Order Service]
Payments[Payment Service]
end
subgraph "Data Layer"
PG[(PostgreSQL)]
Redis[(Redis Cache)]
ES[(Elasticsearch)]
end
Web --> GW
Mobile --> GW
API --> GW
GW --> Auth
GW --> Users
GW --> Products
GW --> Orders
GW --> Payments
Users --> PG
Products --> PG
Products --> ES
Orders --> PG
Orders --> Redis
Payments --> PG
```
API Sequence Diagrams
## Authentication Flow
```mermaid
sequenceDiagram
participant Client
participant Gateway
participant Auth
participant DB
Client->>Gateway: POST /login
Gateway->>Auth: Validate credentials
Auth->>DB: Query user
DB-->>Auth: User data
Auth-->>Auth: Generate JWT
Auth-->>Gateway: JWT token
Gateway-->>Client: 200 OK + token
Note over Client,Gateway: Subsequent requests
Client->>Gateway: GET /api/data (Bearer token)
Gateway->>Auth: Validate token
Auth-->>Gateway: Valid
Gateway-->>Client: 200 OK + data
```
API Documentation
Endpoint Documentation
## User API
### Create User
`POST /api/users`
**Request Body:**
```json
{
"name": "John Doe",
"email": "john@example.com",
"role": "admin"
}
```
**Response:**
```json
{
"id": 123,
"name": "John Doe",
"email": "john@example.com",
"role": "admin",
"created_at": "2024-01-15T10:30:00Z"
}
```
**Status Codes:**
| Code | Description |
|------|-------------|
| 201 | User created |
| 400 | Invalid input |
| 409 | Email exists |
| 500 | Server error |
Class Diagrams for SDKs
## SDK Class Structure
```mermaid
classDiagram
class APIClient {
-string baseUrl
-string apiKey
+get(endpoint) Response
+post(endpoint, data) Response
+put(endpoint, data) Response
+delete(endpoint) Response
}
class UserService {
-APIClient client
+create(user) User
+get(id) User
+update(id, data) User
+delete(id) bool
}
class ProductService {
-APIClient client
+list(filters) Product[]
+get(id) Product
+search(query) Product[]
}
APIClient <|-- UserService
APIClient <|-- ProductService
```
Database Documentation
Entity Relationships
## Database Schema
```mermaid
erDiagram
USERS ||--o{ ORDERS : places
USERS {
int id PK
string email UK
string password_hash
datetime created_at
}
ORDERS ||--|{ ORDER_ITEMS : contains
ORDERS {
int id PK
int user_id FK
decimal total
string status
datetime created_at
}
PRODUCTS ||--o{ ORDER_ITEMS : included_in
PRODUCTS {
int id PK
string name
decimal price
int stock
}
ORDER_ITEMS {
int id PK
int order_id FK
int product_id FK
int quantity
decimal price
}
```
DevOps & Infrastructure
Deployment Pipelines
## CI/CD Pipeline
```mermaid
graph LR
subgraph "Development"
Code[Push Code]
PR[Pull Request]
end
subgraph "CI"
Lint[Lint]
Test[Unit Tests]
Build[Build]
end
subgraph "CD"
Stage[Deploy Staging]
E2E[E2E Tests]
Prod[Deploy Production]
end
Code --> PR
PR --> Lint
Lint --> Test
Test --> Build
Build --> Stage
Stage --> E2E
E2E --> Prod
```
Infrastructure Topology
## AWS Infrastructure
```dot
digraph AWS {
rankdir=TB;
node [shape=box, style=rounded];
subgraph cluster_vpc {
label="VPC";
style=dashed;
subgraph cluster_public {
label="Public Subnet";
ALB [label="ALB"];
NAT [label="NAT Gateway"];
}
subgraph cluster_private {
label="Private Subnet";
ECS [label="ECS Cluster"];
RDS [label="RDS PostgreSQL"];
ElastiCache [label="ElastiCache"];
}
}
Internet [label="Internet", shape=cloud];
S3 [label="S3 Bucket"];
Internet -> ALB;
ALB -> ECS;
ECS -> RDS;
ECS -> ElastiCache;
ECS -> S3;
ECS -> NAT;
NAT -> Internet;
}
```
Code Examples
Syntax Highlighted Code
## Installation
```bash
# Clone the repository
git clone https://github.com/company/project.git
cd project
# Install dependencies
npm install
# Configure environment
cp .env.example .env
vim .env
# Run migrations
npm run db:migrate
# Start development server
npm run dev
```
## Configuration
```typescript
// config/database.ts
import { DatabaseConfig } from './types';
export const config: DatabaseConfig = {
host: process.env.DB_HOST || 'localhost',
port: parseInt(process.env.DB_PORT || '5432'),
database: process.env.DB_NAME || 'myapp',
username: process.env.DB_USER || 'postgres',
password: process.env.DB_PASSWORD,
pool: {
min: 2,
max: 10,
idleTimeoutMillis: 30000
}
};
```
Time Savings
| Document Type | Traditional | With Markdown Viewer |
|---|---|---|
| API doc (10 endpoints) | 2 hours | 30 min |
| Architecture overview | 3 hours | 45 min |
| SDK documentation | 4 hours | 1 hour |
| Deployment guide | 1.5 hours | 20 min |
Why faster?
- No manual diagram drawing
- Code blocks auto-formatted
- One-click export to Word
- Version control friendly
Best Practices
Structure Your Docs
# Project Name
## Overview
Brief description...
## Architecture
System diagrams...
## API Reference
Endpoint details...
## Configuration
Setup instructions...
## Deployment
How to deploy...
## Troubleshooting
Common issues...
Use Consistent Diagrams
Pick a diagram type and stick with it:
- Mermaid for most diagrams
- DOT for complex graphs
- Tables for simple data
Include Examples
Every API endpoint should have:
- Request example
- Response example
- Error examples
Export to Word
When you need to share with non-technical stakeholders:
- Open your documentation
- Press
Ctrl/Cmd + S - Share the Word document
All diagrams become high-resolution images, code keeps syntax highlighting.