Technical Documentation
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.