DDevArchive
Đăng nhập
Thực chiến ⏱️ 18:00 🔥 Nổi bật

Technical writing: README, API docs, và onboarding guide

Code tốt nhưng docs tệ = không ai dùng được. Khi tuyển người mới, docs tốt = onboard 2 ngày thay vì 2 tuần. API docs rõ ràng = ít support ticket hơn. Bài này dạy viết docs mà developer THẬT SỰ ĐỌC.

README: cửa sổ đầu tiên của project

// File: README.md
# DevArchive

> Khoá học lập trình thực chiến từ Zero đến Architect.

## Quick Start

```bash
git clone https://github.com/user/devarchive.git
cd devarchive
cp .env.example .env
npm install
npm run dev

Mở http://localhost:3000

Tech Stack

  • Frontend: Next.js 14, React, TypeScript, shadcn/ui
  • Backend: Next.js API Routes, Prisma
  • Database: PostgreSQL (Supabase)
  • Auth: NextAuth.js
  • Deploy: Vercel

Environment Variables

VariableDescriptionRequired
DATABASE_URLPostgreSQL connection string✅
NEXTAUTH_SECRETRandom string for auth✅
STRIPE_SECRET_KEYStripe API key✅

Contributing

See CONTRIBUTING.md for guidelines.



## API docs: endpoint documentation


API docs tốt có: <strong>endpoint + method + request body + response + error codes + ví dụ curl</strong>. Dùng OpenAPI/Swagger để auto-generate từ code.


## Onboarding guide cho developer mới


| Ngày | Mục tiêu | Tài liệu |
| --- | --- | --- |
| Ngày 1 | Setup môi trường, chạy app local | README + .env.example |
| Ngày 2 | Hiểu architecture tổng quan | Architecture Decision Records (ADR) |
| Ngày 3 | Fix 1 bug nhỏ, tạo PR đầu tiên | CONTRIBUTING.md + PR template |
| Ngày 4-5 | Nhận task đầu tiên, pair programming | Jira/Linear board + senior mentor |


<Callout kind="tip" icon="💡" title="Docs-as-code">
Viết docs ngay trong repo (Markdown), không dùng Google Docs/Notion riêng. Docs trong repo = version controlled, review cùng code, luôn cập nhật. Code thay đổi → docs thay đổi trong cùng PR.
</Callout>


<Quiz question="README nên có thông tin gì TRƯỚC TIÊN?" options={["Lịch sử dự án","Quick Start: cách cài đặt và chạy project trong 5 phút","Danh sách contributors","License"]} answer={1} explain="Người đọc README muốn 1 thứ: chạy được project. Quick Start với &lt;5 bước = ấn tượng tốt nhất. Chi tiết khác để phần sau." />


- [ ] Viết README với Quick Start &lt; 5 bước
- [ ] Tạo .env.example với tất cả biến cần thiết
- [ ] Document ít nhất 3 API endpoints
- [ ] Tạo onboarding guide cho developer mới