-
Notifications
You must be signed in to change notification settings - Fork 0
Engineering doc template
Theo như kinh nghiệm của tôi từ Google, engineering docs là để các thành viên trong team trao đổi và cùng đưa ra quyết định về thiết kế hệ thống. Ví dụ:
- Một hệ thống phần mềm cần bao gồm những components nào?
- Roll back, roll out, release, etc. như thế nào?
- Alert ra sao
- etc. Bộ documents này giúp mọi người hiểu dễ nắm bắt hơn về tổng thể của hệ thống và cũng như giúp mọi người đọc lại nếu có hiểu lầm. Để document được hiệu quả, người viết cần theo một template nhất định và cần liệt kê ra những yếu tố cần có của một hệ thống phần mềm (software system).
Sau đây là template mà mọi người cần follow:
| #1 | #2 |
|---|---|
| Author | Tên người viết |
| Ngày viết | MM/DD/YYYY |
| Lần sửa cuối | MM/DD/YYYY |
| Reviewers | personGithubId [✅], anotherPersonGithubId [❌], anotherGithubId [ ] |
Nói ngắn gọn về những điểm cần đạt được của project V.D: Tạo một service để authenticate user
Yêu cầu kĩ thuật
- Server cần support Firebase
Những yêu cầu khác
- ...
Nói qua về mục đích tại sao lại cần project này, những khó khăn khi không có project này. Nếu có data cụ thể support những data đó thì càng tốt. Cho những project làm việc trực tiếp với trải nghiệm của người dùng (UX), cần viết rõ hơn hoặc có support từ market research trước khi design docs được bắt đầu. Tóm tắt qua những lợi ích khi project này được hoàn thành
Thiết kế của hệ thống, liệt kê bằng các hình vẽ (diagram) để người đọc hiểu được tổng quan của hệ thống (high level design). Sau đó người viết cần phải đưa ra design decision dựa trên tính chất của project (back-end/front-end).
- Tại sao những design đơn giản hơn lại không hợp lý? Nêu ra điểm mạnh/yếu của design này và tại sao lựa chon nó thay cho các design khác.
- Latency (có thể skip nếu mà có human facing task, i.e. front-end). Cụ thể hơn, người design cần phải hiểu được hệ thống này sẽ có bottlenecks ở đâu, và cần đặt ra latency target cho từng hệ thống. Cần đưa ra metrics cho hệ thống và tạo dashboard để theo dõi
- Scalability: hệ thống của bạn scale được như thế nào? Xem xét về lượng data (database, blob storage, etc.) và lượng traffic (request per second) nếu cần thiết.
- Reliability (có thể skip nếu làm front-end): Khi mất data thì bạn xử lý thế nào? Có cần thêm redundancy server/database để handle reliability không? Phương án đã có đã làm thế nào để giải quyết vấn đề reliability? Khi có partial data loss thì xử lý thế nào?
- Các hệ thống liên quan: Xem xét hệ thống này có liên quan như thế nào đến các hệ thống khác, và xử lý như thế nào khi hệ thống ngoài bị sập?
- Security: Tính bảo mật của hệ thống như thế nào?
- Test: bạn test hệ thống ra sao? Unit test, integrated test, load test?
- Monitoring: Theo dõi các thông số ra sao
- Alerts: Khi nào cần thông báo cho người trực (on-call) rằng hệ thống có lỗi và cần sửa gấp?
- Analytics: Có cần thêm hệ thống phân tích thông tin hay không?
- Communications: Cần những hình thức liên lạc như thế nào? v.d. Email, điện thoại, in-app notification, chat?
- Kế hoạch launch project: Tóm tắt về khối lượng công việc, tiến độ xử lý công việc, bao nhiêu người tham gia project, kế hoạc roll back khi có lỗi ra sao
Đưa ra các mục tiêu nhỏ mà project cần đạt được, và đạt được trong bao lâu. Có những yếu tố rủi ro nào sẽ đẩy lùi lại tiến độ của project? Khối lượng công việc và thời gian hoàn thành thực tế có gần được như dự kiến không?
Những việc mà không thể hoàn thành trong project này hoặc timeline này, cần tiếp tục trong một project kế tiếp.