Technical Proposal Structure
Mỗi proposal cần answer 6 câu hỏi: What problem? What solution? What alternatives? How much? When? What risks?
Standard Structure
1. Problem Statement - Vấn đề gì? Ai bị ảnh hưởng? Thiệt hại bao nhiêu?
2. Proposed Solution - Giải pháp recommend
3. Alternatives Considered - Đã xem xét những gì khác? Tại sao không chọn?
4. Cost Analysis - Development, infrastructure, maintenance
5. Timeline & Milestones - Phases, deliverables, dates
6. Risks & Mitigations - Rủi ro và cách giảm thiểu
7. Success Criteria - Làm sao biết thành công?
8. Decision Needed - Cần ai approve? Deadline quyết định?
Writing for Different Audiences
Audience Adaptation Matrix
| Audience | Care About | Format | Detail Level | Length |
|---|---|---|---|---|
| Developers | How, implementation, trade-offs | Markdown, code samples, diagrams | Deep technical | 5-15 pages |
| Engineering Managers | Timeline, resources, risks | Structured doc, tables | Medium technical | 2-5 pages |
| Executives (CTO/VP) | Business impact, cost, timeline | Slides hoặc 1-pager | High-level | 1-2 pages |
| Product Managers | User impact, timeline, dependencies | User stories format | Low technical | 1-3 pages |
Ví dụ cùng 1 proposal - 3 versions
Cho Developer:
"Propose migrate từ Dapper sang EF Core để leverage change tracking, migrations, và LINQ-to-SQL. Trade-off: slight performance overhead (~5-10ms per query) nhưng reduce boilerplate code 60%. Benchmark results attached."
Cho Engineering Manager:
"Propose migrate ORM layer. Giảm 40% development time cho CRUD features. Cần 2 sprints. Risk: learning curve cho team (mitigate: pair programming week 1)."
Cho CTO:
"Đầu tư 4 tuần để modernize data layer → giảm 40% thời gian phát triển features mới → ship nhanh hơn từ Q3. ROI dương sau 3 tháng."
Documentation Types
Comparison Table
| Type | Purpose | When to Write | Template |
|---|---|---|---|
| ADR (Architecture Decision Record) | Record lý do đằng sau technical decisions | Mỗi khi có significant technical choice | Problem → Decision → Consequences |
| RFC (Request for Comments) | Propose thay đổi lớn, thu thập feedback | Trước khi implement significant change | Problem → Proposal → Alternatives → Discussion |
| Runbook | Step-by-step guide cho operations | Mỗi production service | Trigger → Steps → Rollback → Contacts |
| Postmortem | Analyze incidents, prevent recurrence | Sau mỗi significant incident | Timeline → Root Cause → Action Items |
| README | Onboard vào codebase/service | Mỗi repo/service | Overview → Setup → Architecture → Contributing |
ADR Template
markdown# ADR-[number]: [Title]
## Status
Proposed / Accepted / Deprecated / Superseded by ADR-[x]
## Date
[YYYY-MM-DD]
## Context
[Tại sao cần decision này? Background và constraints]
## Decision
[Quyết định cụ thể là gì]
## Alternatives Considered
| Option | Pros | Cons |
|--------|------|------|
| Option A (chosen) | ... | ... |
| Option B | ... | ... |
## Consequences
### Positive
- ...
### Negative
- ...
### Risks
- ...
Postmortem Template
markdown# Postmortem - [Incident Title] - [Date]
## Summary
[1-2 câu mô tả incident]
## Impact
- Duration: [X hours]
- Users affected: [number]
- Revenue impact: [if applicable]
- Severity: [P1/P2/P3]
## Timeline (UTC)
| Time | Event |
|------|-------|
| 14:00 | Alert triggered: API latency > 5s |
| 14:05 | On-call engineer acknowledged |
| 14:15 | Root cause identified: DB connection pool exhausted |
| 14:20 | Mitigation: Increased pool size, restarted service |
| 14:25 | Service recovered |
## Root Cause
[Technical explanation - blameless]
## Contributing Factors
- [Factor 1: Không có alert cho connection pool usage]
- [Factor 2: Load test không cover concurrent scenario này]
## Action Items
| Action | Owner | Priority | Deadline |
|--------|-------|----------|----------|
| Add connection pool monitoring | Dev A | P1 | [Date] |
| Update load test scenarios | Dev B | P2 | [Date] |
| Add circuit breaker for DB connections | Dev C | P2 | [Date] |
## Lessons Learned
- [What went well]
- [What went poorly]
- [Where we got lucky]
Clarity Principles
7 Rules of Clear Technical Writing
| Rule | Bad | Good |
|---|---|---|
| 1. Short sentences | "Hệ thống sẽ được migrate sang microservices architecture mà theo đó mỗi service sẽ handle một bounded context riêng biệt và communicate qua message queue" | "Migrate sang microservices. Mỗi service handle một bounded context. Giao tiếp qua message queue." |
| 2. Active voice | "Database được optimize bởi team" | "Team optimize database" |
| 3. Concrete examples | "Performance cải thiện đáng kể" | "P95 latency giảm từ 800ms xuống 200ms" |
| 4. One idea per paragraph | Wall of text mix nhiều concepts | Mỗi paragraph = 1 point |
| 5. Use headings | Long doc không structure | Clear hierarchy H2 → H3 |
| 6. Tables > prose | Mô tả so sánh bằng paragraph dài | Side-by-side comparison table |
| 7. Visual > text | Mô tả architecture bằng text | Diagram + brief explanation |
Readability Checklist
- Đọc lại một lần - cắt 30% words
- Mỗi sentence < 25 words
- Technical terms giải thích khi lần đầu dùng
- Có TL;DR ở đầu cho docs dài
- Formatting nhất quán (heading levels, bullet styles)
- Links hoạt động, diagrams readable
Tools & Platforms
| Tool | Best For | Pros | Cons |
|---|---|---|---|
| Markdown + Git | ADRs, RFCs, code docs | Version controlled, review qua PR | Không rich editing |
| Confluence | Team wiki, runbooks | Search, permissions, templates | Slow, clunky editor |
| Notion | Team knowledge base | Flexible, databases, nice UX | Không integrate Git |
| Google Docs | Proposals cần collaboration | Real-time collab, comments | Không version control tốt |
| Mermaid | Diagrams as code | Version controlled, embedded in MD | Learning curve |
| draw.io | Complex diagrams | Free, powerful | Separate file management |
Technical Proposal Template (Full)
markdown# [Proposal Title]
**Author:** [Name]
**Date:** [Date]
**Status:** Draft / In Review / Approved / Rejected
**Reviewers:** [Names]
**Decision deadline:** [Date]
## TL;DR
[2-3 câu summary. Đọc xong hiểu đề xuất gì, cost bao nhiêu, timeline bao lâu]
## 1. Problem Statement
### Current State
[Hiện tại hệ thống thế nào]
### Pain Points
- [Pain 1 - quantify impact]
- [Pain 2 - quantify impact]
### Business Impact
[Vấn đề này ảnh hưởng business thế nào: revenue, time-to-market, reliability]
## 2. Proposed Solution
### Overview
[Mô tả giải pháp ở high level]
### Architecture / Design
[Diagram + explanation]
### Key Technical Decisions
| Decision | Rationale |
|----------|-----------|
| Use Redis for caching | Low latency, team có experience |
| Event-driven communication | Loose coupling, scalable |
## 3. Alternatives Considered
| Option | Pros | Cons | Why not chosen |
|--------|------|------|---------------|
| Option A | ... | ... | ... |
| Option B | ... | ... | ... |
## 4. Cost Analysis
| Category | One-time | Monthly | Annual |
|----------|----------|---------|--------|
| Development | X person-weeks | - | - |
| Infrastructure | - | $X | $X |
| Licensing | - | $X | $X |
| **Total** | | | |
## 5. Timeline
| Phase | Duration | Deliverable | Dependencies |
|-------|----------|-------------|-------------|
| Phase 1: Foundation | 2 weeks | Core setup | Team availability |
| Phase 2: Migration | 4 weeks | Data migrated | Phase 1 |
| Phase 3: Rollout | 2 weeks | Production live | Phase 2 + QA |
## 6. Risks & Mitigations
| Risk | Probability | Impact | Mitigation |
|------|------------|--------|-----------|
| [Risk 1] | Medium | High | [Plan] |
| [Risk 2] | Low | High | [Plan] |
## 7. Success Criteria
- [ ] [Measurable outcome 1]
- [ ] [Measurable outcome 2]
## 8. Decision Needed
- [ ] Approve proposal và allocate resources
- [ ] Approve with modifications: [specify]
- [ ] Reject - reason: [specify]
## Appendix
[Technical details, benchmarks, reference links]