Viết SRS cho dự án triển khai nền tảng có sẵn

Một câu thay được rất nhiều trang

Cách xử lý nằm ở mục Mục đích, tức mục đầu tiên của tài liệu, và nó chỉ là một câu.

Câu đó có nội dung như sau:

Hệ thống sẽ ưu tiên kế thừa vận hành theo các luồng chuẩn và mặc định của Odoo, bao gồm các dạng view, search và filter, cách thể hiện dữ liệu và toàn bộ giao diện mặc định; tài liệu này chỉ tham chiếu tới logic mặc định và tập trung mô tả các luồng nghiệp vụ đã được tùy chỉnh, các điểm cần làm rõ, và các phần cần lập trình thêm.

Từ câu đó trở đi, mọi thứ nền tảng đã làm sẵn đều không cần viết lại. Tạo sản phẩm từ phân hệ sản phẩm, tạo sản phẩm ngay trong đơn hàng, thiếu trường bắt buộc thì hệ thống báo lỗi và không cho lưu, tất cả những hành vi đó là mặc định, và tài liệu chỉ mô tả cái bạn làm thêm.

Cần lưu ý rằng số version trong câu đó không phải chi tiết trang trí. Hành vi mặc định của Odoo thay đổi giữa các phiên bản, nên một tài liệu ghi kế thừa mặc định mà không nói mặc định của bản nào thì tới lúc tranh luận sẽ không có căn cứ nào để đối chiếu.

Cái giá của việc không khai báo mặc định

Bỏ qua một câu thì mất gì. Có ba hệ quả, và hệ quả cuối cùng mới là hệ quả đáng sợ.

Hệ quả dễ thấy nhất là tài liệu phình ra: một dự án chỉ có mươi tính năng làm thêm mà tài liệu dày cả trăm trang thì phần lớn nội dung đang mô tả nền tảng, và bạn vừa mất nhiều ngày cho phần không tạo ra giá trị nào.

Nặng hơn chuyện dày mỏng là chuyện không ai đọc. Đội phát triển cần biết chính xác chỗ nào khác mặc định để làm, nếu phải lội qua mấy chục trang mô tả thứ họ đã biết thì họ sẽ bỏ qua tài liệu và hỏi trực tiếp bạn, và tới lúc đó tài liệu chỉ còn là vật trang trí trong hồ sơ nghiệm thu.

Nhưng cái đáng sợ thì không nằm ở tài liệu, nó nằm ở hệ thống. Khi bạn ngồi viết lại từ trí nhớ những gì Odoo vốn đã làm, xác suất viết lệch là rất cao, mà tài liệu đặc tả lại là đầu vào để lập trình và để viết kịch bản kiểm thử, nên chuyện xảy ra sau đó là đội phát triển sửa một hành vi mặc định vốn đang đúng, chỉ vì tài liệu mô tả nó theo cách khác.

Vì vậy nguyên tắc không mô tả lại cái đã có tiết kiệm thời gian ở mặt nổi, nhưng giá trị thật của nó nằm ở chỗ khác: nó là một cơ chế phòng lỗi.

Năm phần lớn của tài liệu

Tài liệu đặc tả hệ thống (SRS) mà tôi dùng chia làm năm phần lớn, đứng trước chúng là phần đầu tài liệu gồm tên dự án, tên hai bên, và bảng ghi nhận thay đổi tài liệu với các cột thời gian, người thực hiện, vị trí, phiên bản và mô tả thay đổi.

Bảng ghi nhận thay đổi là mục dễ bị coi là thủ tục nhất, và cũng là mục cứu bạn khi có tranh chấp, bởi tài liệu được cập nhật liên tục cho tới khi go-live nên nếu không có lịch sử thì không ai biết phiên bản nào đã được duyệt.

• Phần một là tổng quan tài liệu, gồm mục đích, cấu trúc tài liệu, thuật ngữ, và quy định về ký hiệu.
• Phần hai là tổng quan hệ thống, gồm tác nhân và sơ đồ tổng quan.
• Phần ba là các quy trình nghiệp vụ, và ở đây là quy trình tương lai chứ không phải hiện tại.
• Phần bốn là đặc tả yêu cầu hệ thống
• và cuối cùng là bảng mô tả dữ liệu.

Thuật ngữ đặt theo cách khách gọi

Mục thuật ngữ là mục cứu được nhiều cuộc họp nhất so với công sức bỏ ra để viết nó.

Doanh nghiệp nào cũng có từ nội bộ mà người ngoài không hiểu, và nguy hiểm hơn là những từ mà người ngoài tưởng mình hiểu. Trong một dự án xử lý đơn hàng, khách gọi những đơn có cùng mã hàng và cùng số lượng là đơn trùng; từ này nghe qua thì đoán được, nhưng cái quyết định lại nằm ở chỗ đơn trùng được gom lại xử lý theo lô, và nếu không ghi rõ định nghĩa thì đội phát triển sẽ hiểu trùng là trùng khách hàng.

Nguyên tắc tôi giữ là đặt tên theo cách khách gọi chứ không theo cách hệ thống gọi, vì mục đích của bảng thuật ngữ là để hai bên nói cùng một ngôn ngữ. Nếu bạn ép khách dùng từ của bạn thì mọi buổi họp về sau đều mất vài phút để dịch qua dịch lại.

Đồng thời nên đưa vào bảng cả những thiết bị và bên thứ ba xuất hiện trong quy trình, chẳng hạn thiết bị quét mã cầm tay (barcode) dùng trong kho, bởi những thứ đó về sau sẽ xuất hiện trong phần tác nhân và trong sơ đồ hệ thống.

Quy định về ký hiệu

Mục này chỉ có giá trị nếu tài liệu của bạn có sơ đồ, và nó tồn tại vì một lý do rất thực tế, đó là người đọc tài liệu không phải ai cũng biết đọc sơ đồ quy trình.

Khi tài liệu dùng BPMN thì sáu ký hiệu tôi hay phải khai báo gồm điểm bắt đầu và kết thúc, bước thực hiện, tham chiếu tới một quy trình khác, cổng rẽ nhánh loại trừ, cổng song song và cổng bao gồm. Nếu tài liệu dùng flowchart thì bộ ký hiệu khác hẳn và ngắn hơn.

• Cổng rẽ nhánh loại trừ nghĩa là chỉ nhánh nào thỏa điều kiện mới chạy, ví dụ đơn dưới hạn mức thì đi thẳng, đơn vượt hạn mức thì sang luồng duyệt.
• Cổng song song nghĩa là tất cả các nhánh đều phải hoàn tất thì mới đi tiếp, ví dụ một đơn hàng chỉ được coi là hoàn tất khi đã xong cả phần thanh toán lẫn phần giao hàng.
• Cổng bao gồm nghĩa là một hoặc nhiều nhánh thỏa điều kiện đều được thực hiện, ví dụ khách thanh toán một phần bằng tiền mặt và một phần bằng chuyển khoản.

Ký hiệu tham chiếu tới quy trình khác là ký hiệu tiết kiệm công sức nhất trong danh sách. Khi quy trình bán hàng kết thúc và chuyển sang quy trình giao hàng, bạn không vẽ lại toàn bộ quy trình giao hàng vào sơ đồ bán hàng mà chỉ đặt một ký hiệu tham chiếu; nhờ vậy mỗi quy trình được vẽ đúng một lần và khi nó thay đổi thì bạn chỉ sửa một chỗ.

Tác nhân người và tác nhân hệ thống

Phần tác nhân chia làm hai loại.

Tác nhân là người thì mô tả chức vụ, công việc trong quy trình, và thao tác trên thiết bị nào. Chi tiết thiết bị nghe như thừa nhưng lại quan trọng, vì một người thao tác trên máy quét cầm tay trong kho có nhu cầu giao diện hoàn toàn khác một người ngồi máy tính ở văn phòng, và nếu tài liệu không ghi thì đội phát triển sẽ thiết kế màn hình theo mặc định là màn hình máy tính.

Tác nhân là hệ thống thì mô tả các hệ thống bên ngoài tham gia vào luồng, chẳng hạn các sàn thương mại điện tử đổ đơn về, hệ thống hóa đơn điện tử, hay thiết bị quét mã kết nối trực tiếp với máy in. Chi tiết kết nối trực tiếp đó rất đáng ghi, bởi nó xác định rằng việc in không do hệ thống chính điều khiển, và nếu ghi sai thì phát sinh cả một hạng mục lập trình không cần thiết.

Đặc biệt, nếu dự án của bạn chỉ triển khai một hệ thống Odoo, không có app ngoài và không có tích hợp nào, thì bỏ hẳn mục tác nhân hệ thống. Viết một mục chỉ để ghi rằng hệ thống duy nhất là chính nó thì không giúp gì cho người đọc.

Sơ đồ tổng quan và chuyện một chiều hay hai chiều

Sơ đồ tổng quan hệ thống chỉ có ý nghĩa khi dự án có tích hợp, và nội dung của nó là các luồng dữ liệu giữa những tác nhân hệ thống vừa liệt kê.

Thứ duy nhất phải ghi thật rõ trên sơ đồ này là mỗi luồng đi một chiều hay hai chiều. Chẳng hạn kết nối với sàn thương mại điện tử thường là hai chiều, tức đơn hàng đổ về hệ thống và hệ thống đẩy ngược trạng thái cùng số lượng tồn kho lên sàn; còn kết nối với hệ thống hóa đơn điện tử thường chỉ một chiều, tức hệ thống đẩy dữ liệu sang và không nhận gì về.

Chi tiết này quyết định khối lượng lập trình một cách trực tiếp, bởi một luồng hai chiều thì phải xử lý thêm chuyện đồng bộ ngược, xử lý xung đột khi hai bên cùng thay đổi, và xử lý trường hợp gọi lại thất bại. Một mũi tên vẽ thiếu đầu ở đây có thể là vài ngày công không nằm trong ước lượng.

Đặc tả từng tính năng

Phần bốn chia theo phân hệ hoặc theo tính năng, rồi chia nhỏ theo từng quy trình, và mỗi tính năng được đặc tả theo một cấu trúc cố định gồm mười một mục:

1. tên tính năng
2. mô tả
3. tác nhân
4. điều kiện trước
5. sự kiện kích hoạt
6. điều kiện sau
7. luồng chính
8. luồng thay thế
9. luồng ngoại lệ
10. quy tắc nghiệp vụ
11. và cuối cùng là phần giao diện gồm ảnh chụp có đánh số kèm bảng mô tả các thành phần

Trong mười một mục đó, ba mục về luồng và mục quy tắc nghiệp vụ là bốn mục mang toàn bộ giá trị của tài liệu, còn phần giao diện là mục quyết định năng suất của mọi việc diễn ra sau khi go-live. Cả hai nhóm này đủ dài để nói riêng nên tôi không đi sâu ở đây.

Điều đáng nói ở mức tổng quan là nguyên tắc kế thừa mặc định vẫn tiếp tục áp dụng bên trong từng mục. Nếu Odoo đã chặn việc lưu khi thiếu trường bắt buộc thì bạn không liệt kê nhánh đó vào luồng ngoại lệ; chỉ những nhánh phát sinh từ quy tắc nghiệp vụ của chính doanh nghiệp mới cần viết ra.

Bản dùng khi hợp đồng không bàn giao

Không phải dự án nào cũng bàn giao tài liệu đặc tả cho khách, và mức độ chỉn chu nên đi theo chuyện đó chứ không đi theo cảm giác làm nghề. Việc cắt tài liệu tới đâu thì tôi đã đặt thành nguyên tắc chung ở bài bộ tài liệu dự án ERP, nên ở đây chỉ nói phần riêng của tài liệu đặc tả.

Ba phần đầu bỏ được, vì thông tin đó đã nằm ở lưu đồ và báo cáo khảo sát. Ngay trong phần bốn thì mục mô tả, điều kiện trước và sự kiện kích hoạt cũng là ba mục bỏ đi mà không ai kẹt, bởi người đọc nội bộ đã biết tính năng này sinh ra từ đâu.

Cái không cắt được thì thuộc về ba luồng và quy tắc nghiệp vụ, cộng với bảng trường dữ liệu và ảnh chụp màn hình, bởi đây là những mục duy nhất mà mặc định của hệ thống không tự trả lời thay bạn được.

Dựng mockup bằng chính hệ thống

Còn một mẹo nữa tiết kiệm được nhiều thời gian, và nó tận dụng đúng đặc thù của việc triển khai nền tảng có sẵn.

Thay vì vẽ giao diện bằng công cụ thiết kế như Figma rồi mô tả lại, bạn kéo thẳng các trường cần thêm lên màn hình thật bằng Studio, một công cụ của bản Enterprise, rồi chụp lại. Cách này đổi một bản vẽ lấy một màn hình thật, nên khách nhìn thấy đúng thứ họ sẽ dùng và phản hồi của họ cụ thể hơn hẳn.

Tuy nhiên nó kéo theo hai ràng buộc. Ràng buộc thứ nhất thuộc về tài liệu: nếu dự án dùng Studio cho phần sản phẩm bàn giao thì phải ghi việc đó ngay ở mục tổng quan hệ thống, vì tên kỹ thuật của trường tạo theo cách này mang tiền tố riêng. Ràng buộc thứ hai lớn hơn và thuộc về cách làm nghề, đó là ranh giới giữa việc kéo tay và việc viết code, cùng chuyện mockup nên dựng trên môi trường nào; tôi đã nói riêng chuyện đó ở bài về nguyên tắc bàn giao mã nguồn.

Tài liệu sống cho tới ngày go-live

Điểm cuối cùng, và cũng là điểm dễ bị bỏ qua nhất, là tài liệu đặc tả không đóng lại ở thời điểm được duyệt lần đầu.

Khi khách bắt đầu dùng thử, sẽ có tính năng họ thấy không cần nữa, và sẽ có chỗ phải chỉnh cho hợp thói quen người dùng. Mỗi thay đổi như vậy đều phải quay lại tài liệu, ghi vào bảng lịch sử thay đổi, và gửi lại cho hai bên xác nhận; nếu không thì tới lúc nghiệm thu, hai bên đối chiếu hai phiên bản khác nhau của cùng một file.

Chuyện tiếp theo là phần nằm giữa tài liệu này, tức ba luồng nghiệp vụ và cách viết chúng cho không sót trường hợp nào.