Một chút về việc làm tài liệu specs cho dự án

Jul 27, 2021

Hế lô cả nhà.

Hôm nay một chiếc chiếu mới mạn phép viết một bài tản mạn chút về cái gọi là documentation(việc làm tài liệu).

Thực ra là cũng định tìm tài liệu offical cho vấn đề này và chia sẻ kiến thức chuẩn chỉnh cho mọi người, tuy nhiên thì chả tìm được gì mấy nên thôi chia sẻ kinh nghiệm cá nhân vậy. Có gì sai sót anh chị em cứ thẳng tay góp ý để cùng cải thiện nhé ạ :D

So...

1. Tài liệu specs là gì?

Trong một dự án thì cơ bản sẽ có những tài liệu:

・Requirement Definition: tài liệu mô tả yêu cầu và mong muốn của KH

・Design: tài liệu design cơ bản và chi tiết cho team phát triển

・Programming Document: tài liệu kỹ thuật

・Test Document: tài liệu test

Tài liệu specs mình đang muốn nói đến là tài liệu nằm trong đống Requirement Definition. Nó là tài liệu mô tả nghiệp vụ của hệ thống, nói một cách nôm na thì nó mô tả hệ thống trong thực tế dùng để làm gì và end user sẽ dùng, thao tác hệ thống như thế nào, hệ thống trả về kết quả ra làm sao.

Tài liệu specs sẽ được sử dụng như là input để làm các tài liệu khác.

2. Ai sẽ làm tài liệu?

Thông thường thì khách hàng(Product Owner(PO)) sẽ là người làm và cung cấp Requirement Definition, Business Analytics(BA) sẽ phân tích để làm rõ để team có thể triển khai. Tất nhiên đây là process lý tưởng. Sẽ có những trường hợp PO chỉ đưa ra ý tưởng sơ khai và chúng ta sẽ phải nghĩ cho họ mọi thứ còn lại(cái này là ở cái tầm cung cấp giải pháp roài).

OK, hết lý thuyết nhé. Quay lại với phần chia sẻ.

3. Khi mới vào dự án mình muốn gì?

Chắc chắn đó là overview.

Mình đã từng làm một dự án. Do dự án chạy gấp nên giai đoạn làm tài liệu bị rút ngắn. Lúc mình vào thì chỉ nhận được tên dự án + design màn hình cộng thêm một chút mô tả chỗ này nhập cái gì, click chỗ này thì sẽ làm gì. Hệ thống hơn 100 màn hình, đa phần các màn hình cũng chỉ đơn giản là CRUD (create/ read/ update/ delete). Sao mà lắm CRUD thế, mục đích của mỗi phần là gì, bọn nó liên quan với nhau như thế nào vậy, hoang mang vô cùng. Tôi cần một cái overview để liên kết toàn bộ kiến thức lại với nhau...

Overview tức là sản phẩm của dự án là gì, nó được dùng như thế nào và để làm gì trong thực tế.

Ví dụ: thay vì chỉ ghi "hệ thống chụp ảnh và phân tích ảnh chụp được" thì nên là "hệ thống chụp ảnh biển số xe khi xe đến trạm thu phí, phân tích biển số chụp được để...". Với thông tin như vậy thì dù chưa đi vào specs chi tiết cũng đã có thể mường tượng ra hệ thống sẽ hoạt động như thế nào rồi.

Có overview rồi thì bạn có thể:

  • Dễ dàng tưởng tượng được flow của hệ thống bằng việc liên tưởng đến thực tế.
  • Có keyword để tự tìm hiểu, google nếu tài liệu dự án chưa đầy đủ.
  • Hiểu bản chất của chức năng giúp đánh giá được specs có hợp lý không.

Vậy tài liệu overview nên có gì?

① Mô tả bối cảnh và nghiệp vụ thực tế của hệ thống.

② Screen Flow(luồng di chuyển của toàn bộ màn hình)

③ Activity Diagram(luồng thao tác của người dùng)

Theo mình nghĩ như vậy là okay. Tất nhiên tùy mỗi dự án, không nhất thiết là phải đủ cả 3, nhưng số ① thì luôn là nên có.

4. Xong overview rồi thì sẽ cần gì tiếp theo?

Xong cái tổng thể thì phải vào chi tiết thôi, thế cũng phải hỏi :v

Tùy vào tính chất của mỗi dự án mà tài liệu chi tiết nó cũng có thế khác nhau. Mình đã từng kinh qua 3 kiểu tài liệu dưới đây nên tiện review cho mọi người nhé.

① Tài liệu mô tả business và nghiệp vụ hệ thống.

Đây là kiểu tài liệu phổ biến nhất và hầu hết các dự án đều dùng được.

Nó mô tả nghiệp vụ bằng “ngôn ngữ con người”. Chẳng hạn như “Hiển thị toàn bộ sản phẩm tìm được lên Grid View. Sort theo alphabet DESC…)

・Ưu điểm: chi tiết và hướng đến nhiều đối tượng. Mọi đối tượng trong team dù không có kỹ thuật đều có thể đọc được.

・Nhược điểm: “nhiều chữ” dẫn đến lười đọc. Tài liệu có thể bị khó đọc hoặc khó hiểu do người viết “dốt văn” :v  → Có thể được cải thiện bằng một template xịn sò

② Tài liệu mô tả theo hướng kỹ thuật

Tài liệu viết theo hướng “ngôn ngữ máy”.

Điển hình là kiểu mô tả dựa theo format của tài liệu API design cộng thêm biến tấu để bổ sung thêm thông tin I/O hoặc validation cần thiết.

・Ưu điểm: ngắn gọn, rất dễ đọc và implement cho team dev. Không cần học sinh giỏi văn ở đây.

・Nhược điểm: Khó đọc đối với thành viên không có kỹ thuật hoặc member mới. Member chỉ nhận thức được logic của hệ thống, không nắm được business thực tế.

③ Diagram

Thay bằng viết bằng chữ thì tài liệu này mô tả theo hình vẽ, flow.

Hoàn toàn có thể vẽ theo hướng mô tả flow business hoặc flow kỹ thuật.

・Ưu điểm: ngắn gọn, dễ đọc dễ hiểu và nhìn thấy rõ luồng.

・Nhược điểm: không thể chi tiết được như kiểu ① và ② nên thường phải kết hợp với 1 trong 2 loại đó.

5. Tài liệu specs cần chi tiết đến mức nào?

Câu trả lời tất nhiên là chi tiết hết mức có thể. Tuy nhiên còn phải tùy vào việc mình đang làm tài liệu cho giai đoạn nào.

Như đã nói ở trên, tài liệu specs sẽ được sử dụng là input cho các tài liệu khác.

・Ở giai đoạn làm 見積 chẳng hạn thì specs sẽ chỉ cần ở mức đầy đủ số lượng màn hình, chức năng... để có thể estimate được.

・Ở giai đoạn làm basic design thì lại cần làm rõ từng chức năng, mối quan hệ lẫn nhau… để build được cái structure, cái khung cho hệ thống.

・Từ giai đoạn làm details design về sau thì sẽ phải là càng chi tiết càng tốt, mô tả đến từng case validate để có thể implement và lên test case.

Việc làm tài liệu specs cũng bị ảnh hưởng rất nhiều từ tiến độ và số lượng requirement nhận được từ PO nữa.

Tóm lại là tài liệu specs không thể pơ phệch ngay từ đầu được. Tùy vào giai đoạn và lượng thời gian để làm tài liệu ở mức phù hợp, tránh việc quá tham chi tiết dẫn đến chậm deadline.

6. Có phải mọi thông tin trong file specs đều quan trọng như nhau?

7. Tổ chức file làm sao để mọi người đều có thể dễ tìm đến cái mình cần?

8. Khi có Change Request(CR) thì phải làm sao?

9. Hãy nhớ chú thích

Ôi bàn phím hỏng mất rồi, để mình đi sửa cái đã =)))) Hẹn mọi người phần 6789 ở một bài khác :v

À, về chủ đề này, nếu ai có vấn đề cần đàm đạo thì raise lên cùng thảo luận nhé.

Thanks for reading me!!!

Great! You've successfully subscribed.
Great! Next, complete checkout for full access.
Welcome back! You've successfully signed in.
Success! Your account is fully activated, you now have access to all content.