Bảng GUI element và vì sao nó quyết định năng suất về sau

Không ai sai ở đây cả. Người viết bảng đó đã điền đủ mọi ô, không bỏ trống dòng nào, và tài liệu đã được duyệt.

Vấn đề nằm ở chỗ khác: bảng mô tả trường là mục trông giống thủ tục hành chính nhất trong toàn bộ tài liệu đặc tả, nên nó được điền cho đầy chứ không được viết cho dùng. Và cái giá của chuyện đó không rơi vào lúc viết, nó rơi vào nhiều tháng sau, ở một chỗ khác, cho một người khác.

Bản chất của bảng mô tả trường dữ liệu

Cách nhìn giúp tôi thay đổi hoàn toàn thái độ với mục này là ngừng coi nó như phần mô tả và bắt đầu coi nó như dữ liệu có cấu trúc.

Một bảng mô tả trường dữ liệu viết đúng sẽ chứa mô tả có cấu trúc của một màn hình: mỗi dòng một thành phần, mỗi cột một thuộc tính, và giữa các dòng có quan hệ rõ ràng. Thứ có cấu trúc như vậy thì máy đọc được, và cái gì máy đọc được thì về sau sinh ra được thứ khác.

Ngược lại, một bảng viết cho có thì chỉ là văn bản. Nó không sinh ra được tài liệu hướng dẫn sử dụng, không sinh ra được danh sách trường cần dịch, không đối chiếu được với hệ thống thật để biết cái gì đã đổi, nên mọi việc phía sau đều phải làm lại từ đầu bằng tay, và người làm lại thường không phải là bạn.

Do đó câu hỏi đúng khi ngồi trước bảng này không phải là điền thế nào cho đủ, mà là vài tháng nữa ai sẽ đọc nó và họ cần lấy ra được cái gì.

Bảy cột và lý do tồn tại của từng cột

Bảng mẫu trong các tài liệu hướng dẫn thường có sáu cột kể cả cột số thứ tự. Bảng thiết kế dữ liệu trong bộ template tôi dùng cho phần tùy biến thì có bảy cột nội dung, và hai cột chênh lệch là hai cột đáng nói nhất.

Lưu ý rằng, khách hàng của bạn sử dụng ngôn ngữ nào thì bạn cần bổ sung thêm hiển thị (dịch thuật) của ngôn ngữ đó.

Cột tên kỹ thuật là cột dễ bị bỏ nhất vì người viết tài liệu nghĩ đó là việc của đội phát triển. Thực tế thì ngược lại: một khi hệ thống đã được Việt hóa, tên hiển thị trên màn hình không còn khớp với tên trong mã nguồn, nên nếu tài liệu chỉ ghi tên tiếng Việt thì mọi cuộc trao đổi giữa bạn và đội phát triển đều phải bắt đầu bằng việc dò xem đang nói về trường nào. Chuyện này còn rõ hơn ở phần phân quyền, nơi bạn phải khai báo theo tên kỹ thuật của đối tượng dữ liệu chứ không theo tên hiển thị, bởi tên hiển thị đổi theo ngôn ngữ còn tên kỹ thuật thì không.

Cột mô tả là cột dễ bị điền cho có nhất, và có một cách kiểm rất nhanh: nếu xóa cột tên trường đi mà người đọc vẫn đoán được trường này là gì thì mô tả đạt, còn nếu mô tả chỉ là tên trường viết lại thành câu thì nó không mang thông tin nào. Mô tả tốt trả lời hai chuyện, giá trị này dùng để làm gì trong nghiệp vụ, và ai là người nhập nó.

Hai cột mà nhiều mẫu không có

Cột tách tên tiếng Anh khỏi tên tiếng Việt (hoặc bất kỳ ngôn ngữ nào khác) tồn tại vì một đặc điểm rất cụ thể của nền tảng: Odoo lưu chuỗi tiếng Anh làm khóa rồi tra bản dịch theo ngôn ngữ mà người dùng chọn.

Vì vậy bảng trường tách hai cột không phải để cho đầy đủ mà để ép chính người viết phải quyết định tên tiếng Anh ngay từ lúc thiết kế. Lý do phải đặt nhãn tiếng Anh trước rồi dịch sau nằm ở cơ chế lưu bản dịch của nền tảng, và đã có bài riêng nói kỹ.

Cột tooltip thì nhỏ hơn nhiều nhưng có tác dụng trực tiếp lên chất lượng dữ liệu. Người dùng cuối gặp một trường không hiểu để làm gì thì họ có hai lựa chọn, bỏ trống hoặc nhập bừa, và cả hai đều tạo ra dữ liệu mà sau này bạn phải đi dọn. Một câu gợi ý hiện ra khi họ đưa chuột vào ô là cách rẻ nhất để tránh chuyện đó, rẻ hơn nhiều so với một buổi đào tạo lại.

Cần lưu ý rằng tooltip cũng là cột duy nhất trong bảy cột mà bộ template ghi rõ là có thể bỏ qua. Sáu cột còn lại thì tôi không bỏ, và lý do của từng cột nằm ngay ở bảng trên.

Viết theo kiểu dữ liệu

Không phải trường nào cũng mô tả giống nhau, và với mỗi kiểu field thì có một thứ bắt buộc phải ghi thêm. Đây là phần mà tài liệu viết cho có hay bỏ sót nhất.

Trường kiểu lựa chọn (selection) thì phải liệt kê đầy đủ các giá trị, chẳng hạn loại khách hàng gồm khách lẻ và khách sỉ, bởi ghi thiếu một giá trị thì đội phát triển làm thiếu và người dùng phát hiện ra trong buổi kiểm thử.

Nhóm trường quan hệ thì nặng hơn một bậc, vì với chúng bạn bắt buộc phải ghi rõ trường trỏ tới đối tượng dữ liệu nào. Ghi "người phụ trách" mà không nói trỏ tới danh sách người dùng hệ thống hay danh sách nhân viên là hai chuyện hoàn toàn khác nhau về mặt dữ liệu và về mặt phân quyền. Riêng trường quan hệ hiển thị dạng danh sách kẻ bảng thì phải mô tả thêm bảng đó hiển thị những cột nào, bởi nếu không nói thì đội phát triển sẽ để mặc định, và mặc định gần như chắc chắn không phải cái người dùng cần nhìn.

Một chi tiết nữa hay bị bỏ qua vì nó nhìn như chuyện giao diện là tiện ích hiển thị gắn trên trường, nhưng nó ảnh hưởng tới cách dữ liệu được nhập vào: một trường số điện thoại về bản chất là trường ký tự, còn khi có tiện ích định dạng đi kèm thì số nhập vào sẽ được tự căn theo khuôn, và người dùng nhìn thấy một trải nghiệm khác hẳn.

Ngoài ra, nếu tính năng cần tạo một đối tượng dữ liệu mới thì phải ghi tên đối tượng đó cùng các dạng xem sẽ có, chứ không chỉ liệt kê trường. Thiếu phần này thì đội phát triển tạo đủ trường nhưng người dùng không có màn hình nào để mở chúng lên.

Mặt trái của nguyên tắc kế thừa mặc định

Một nguyên tắc chung của việc viết tài liệu cho nền tảng có sẵn là không mô tả lại cái đã có. Tuy nhiên nguyên tắc đó có mặt trái, và mặt trái nằm ở chỗ nếu bạn im lặng thì hệ thống sẽ chạy theo mặc định của nó chứ không theo mong muốn của khách.

Hai chỗ hay gặp nhất là bộ lọc và danh sách hiển thị. Nếu tài liệu không mô tả gì thì người dùng chỉ có bộ lọc tự dựng, và danh sách bản ghi hiển thị rất ít thông tin, trong khi thứ user thật sự cần thường là mở danh sách lên thấy ngay vài cột quan trọng và lọc nhanh theo vài tiêu chí quen thuộc.

Do đó nếu user có yêu cầu về chuyện này thì phải viết ra, còn nếu không thì cũng nên hỏi. > Một câu hỏi trong buổi khảo sát như “mở danh sách này lên anh chị muốn nhìn thấy ngay những thông tin gì”, thường tiết kiệm được cả một vòng chỉnh sửa sau kiểm thử.

Nguồn lấy thông tin trên hệ thống

Phần lớn thông tin trong bảy cột nằm sẵn trên hệ thống, và bạn tự lấy được mà không cần hỏi đội phát triển.

Bật chế độ nhà phát triển rồi đưa chuột lên dấu chấm hỏi nhỏ nằm ngay sau nhãn của một trường bất kỳ, hệ thống hiện ra một khối thông tin trong đó có nhãn hiển thị, tên trường, đối tượng chứa nó và kiểu dữ liệu. Điểm rê chuột đúng là dấu chấm hỏi ấy chứ không phải dòng chữ nhãn, còn trên dạng xem danh sách thì bạn rê thẳng lên tiêu đề cột, và cách đọc đầy đủ khối thông tin đó là chủ đề của bài về chế độ nhà phát triển. Hai mục lấy nguyên về làm cột trong bảng là tên trường và kiểu dữ liệu; còn tên đối tượng thì không thành một cột riêng nhưng lại là thứ bạn cần khi mô tả các trường quan hệ, nên đừng bỏ qua nó.

Với những trường bạn định thêm mới thì có một cách nhanh hơn, đó là kéo thử bằng công cụ tùy biến giao diện của bản Enterprise: kéo xong là có ngay giao diện thật để chụp, có luôn kiểu dữ liệu và đối tượng liên kết chính xác, và có một bản demo để đưa khách xem. Cần lưu ý rằng trường tạo theo cách này mang tiền tố riêng trong tên kỹ thuật, và việc chọn kéo tay hay viết code kéo theo cả một nguyên tắc riêng mà tôi đã nói ở chỗ khác.

Ảnh chụp màn hình và cách đánh số

Bảng trường không đứng một mình, nó luôn đi kèm ảnh chụp giao diện, và cách chụp quyết định giá trị của cả cụm.

Nguyên tắc là chụp xong thì đánh số các thành phần trên ảnh, và số đó phải khớp với thứ tự dòng trong bảng; nếu bảng của bạn chưa có cột số thứ tự thì thêm một cột như vậy vào trước cột tên kỹ thuật, vì nếu không thì người đọc phải tự đếm dòng. Người đọc nhìn ảnh thấy số ba, tra bảng dòng ba, biết ngay đó là trường gì và để làm gì.

Trong trường hợp màn hình chỉ thêm vài trường mới so với mặc định thì có thể khoanh vùng phần mới thay vì đánh số toàn bộ, như vậy nhanh hơn và người đọc cũng thấy ngay đâu là phần được làm thêm.

Đồng thời, nếu tính năng có nhiều trạng thái mà mỗi trạng thái hiện ra một tập trường khác nhau thì nên chụp cả những trạng thái đó, bởi một ảnh duy nhất sẽ khiến người đọc tưởng rằng màn hình chỉ có bấy nhiêu. Ảnh chụp ở đây phục vụ một tài liệu đã chốt; còn khi cần lấy xác nhận giao diện từ khách trước khi chốt, kỹ thuật dựng thẳng mockup trên hệ thống thay vì vẽ ngoài là một chủ đề riêng.

Lợi ích trả về muộn

Tất cả những chi tiết ở trên đều tốn công, và công đó bỏ ra ở giai đoạn thiết kế trong khi lợi ích chỉ hiện ra sau khi hệ thống chạy. Đây chính là lý do mục này hay bị làm ẩu, nên đáng nói rõ lợi ích đó là gì.

Lợi ích rõ nhất nằm ở tài liệu hướng dẫn sử dụng. Một bộ hướng dẫn về bản chất là ảnh màn hình cộng mô tả từng thành phần cộng các bước thao tác, mà ba thứ đó bạn đã có sẵn trong tài liệu đặc tả nếu bảng trường được viết tử tế, nên phần việc lặp đi lặp lại này giao được cho công cụ hỗ trợ làm phần thô còn bạn chỉ rà lại; ngược lại, nếu bảng viết cho có thì người viết hướng dẫn phải mở hệ thống lên xem lại từng màn hình, tức là làm lại đúng công việc mà bạn đã làm một lần.

Kế đó là kiểm thử, và ở đây bảng mô tả trường dữ liệu trả lời sẵn ba câu mà người viết kịch bản luôn phải hỏi, gồm:

• trường nào bắt buộc
• trường nào có danh sách giá trị cố định
• và trường nào trỏ tới đối tượng khác

Cột tên tiếng Anh thì lại có một công dụng ít ai nghĩ tới vào lúc điền, đó là nó chính là danh sách chuỗi cần dịch, nhờ vậy việc Việt hóa phần tùy biến trở thành một việc có danh sách rõ ràng thay vì một việc đi dò khắp hệ thống xem còn chỗ nào chưa dịch.

Còn lợi ích xa nhất thì tôi đã nói ở bài về tài liệu đặc tả, nên ở đây chỉ nhắc một câu: khi có người tiếp quản hệ thống này, bảng mô tả trường dữ liệu là thứ cho họ biết dự án đã làm thêm những gì mà không phải đọc ngược từ source code.

Cả bốn lợi ích đó đều đến muộn và đều đến ở chỗ khác, nên nếu bạn chờ cảm nhận được chúng rồi mới làm cho tử tế thì sẽ không bao giờ tới lúc đó. Công bỏ ra thì nhỏ và đo được ngay, còn công tiết kiệm được thì lớn nhưng nằm rải rác ở nhiều người và nhiều thời điểm, và không có cơ chế nào trong dự án ép bạn làm đúng ngay từ đầu ngoài chính bạn.

Tới đây thì bộ tài liệu đã đủ để đội phát triển bắt tay vào làm, và câu hỏi kế tiếp không còn là viết gì nữa mà là làm thêm bằng cách nào, tức cấu hình tới đâu thì dừng và từ đâu thì buộc phải viết code. Tuy nhiên, tất cả ví dụ tôi nói đều mượn trên hệ thống Odoo.