Hãy thử suy ngẫm về tài liệu　

Trong lĩnh vực phát triển phần mềm, mỗi khi nhắc tới “tài liệu (document)” các bạn thường nghĩ đến gì? Các bạn nghĩ đến Requirement Definition (Bản định nghĩa yêu cầu), Functional specification (Bản đặc tả chức năng), Inspection plan (Kế hoạch kiểm thử), Test Result Report (Báo cáo kết quả kiểm thử) v.v…à? Tất nhiên, những cái đó chính là tài liệu.

Tuy nhiên, đó không phải là tất cả. Lần này, tôi sẽ thử truyền tải đến các bạn suy nghĩ của bản thân tác giả là tôi về document. Ngoài ra, những biểu đồ nêu trong bài viết cũng chịu ảnh hưởng từ nội dung câu chuyện giữa tác giả và bạn của tác giả - người có nhiều thành tích trong cộng đồng Ruby, Agile – Shintaro Kakutani-san, trước khi thực hiện bài viết này.

Khi thực hiện cấu trúc hệ thống phần mềm, chương trình là người vận hành hệ thống thực tế nên có lẽ sẽ có người hình dung như Figure.1. Nói cách khác, hệ thống chủ yếu được cấu thành bởi chương trình nên tài liệu tồn tại một cách độc lập với nó.

Figure.1

Nhưng, thực thế các bạn phải nghĩ được giống như Figure.2, nghĩa là “Tài liệu là yếu tố cấu thành quan trọng của hệ thống nên không thể tách biệt nó ra khi suy nghĩ được”. Bởi vì tài liệu phải là thứ cung cấp giá trị nào đó cho những người có liên quan đến hệ thống. Nói cách khác thì tài liệu mà không cung cấp giá trị gì là tài liệu vô ích nên vốn dĩ là không cần tạo những loại tài liệu như vậy.

Figure.2

Trong quy trình phát triển theo dạng thức phase gate, những tài liệu chỉ tồn tại với mục đích để được thông qua phase gate thì không mang lại giá trị thực tế nên nếu có thể thay thế bằng phương pháp khác thì nên tích cực cố gắng loại bỏ loại tài liệu này đi. Ngoài ra, dù không thể loại bỏ một cách triệt để nhưng việc sử dụng cơ chế tự động hóa mà lần trước tôi giới thiệu, làm cho generate tự động để giảm công sức của con người cũng có hiệu quả. Không phải “Vì bị nói nên tạo tài liệu.”mà là quan trọng là tự mình nên thử suy nghĩ xem “Đã phải là tài liệu nâng cao giá trị của hệ thống chưa?”

Ngoài ra, không giới hạn trong phạm vi tài liệu mà chúng ta hãy luôn luôn lưu tâm đến không chỉ việc tạo ra hệ thống mà còn cả việc bảo trì hệ thống sau này.Việc tạo ra hệ thống cho lần release đầu tiên nếu xét trong cuộc đời một con người thì chỉ giống như thời kỳ vẫn còn là bào thai trong bụng mẹ. Giống như con người, cuộc sống sau khi được sinh ra mới là nhân sinh thực sự thì đối với hệ thống, thời gian sau lần release đầu tiên mới càng quan trọng hơn. Bởi vì việc hệ thống có thực sự đem lại giá trị hay không phải xem trong thời gian bảo trì hay giai đoạn phát triển phái sinh. Chúng ta là sinh vật dễ quên. Có nội dung chỉ nói miệng lúc tạo là xong nhưng cũng có thông tin phải ghi thành tài liệu để phục vụ cho việc bảo trì. Tài liệu có thể khiến cho việc bảo trì trở nên dễ dàng không nghi ngờ gì sẽ giúp nâng cao giá trị của hệ thống.

Thêm nữa, nếu xem kỹ Figure.2 các bạn sẽ hiểu. Khung chữ nhật của chương trình và tài liệu đang đè lên nhau. Ý muốn thể hiện ở đây là chương trình cũng được xem như tài liệu ở một khía cạnh nào đó. Cụ thể hơn nữa, chương trình chính là loại tài liệu quan trọng nhất.

Không phải chỉ có file được tạo bằng Word, Excel hay PowerPoint mới là tài liệu. Đúng vậy, chương trình chính là loại tài liệu ghi lại tất cả các thông tin hệ thống thực hiện gì (What), thực hiện như thế nào (How) (Ngay cả bug cũng được ghi một cách chính xác!”). Cụ thể, chương trình được nói đến ở đây không chỉ là code sản phẩm mà bao gồm cả những công cụ hỗ trợ như code dùng để test hay autobuilt script v.v...

Nói như vậy nhưng để viết được chương trình có giá trị như một tài liệu thì cần phải có khá nhiều kỹ năng. Ví dụ như chú ý thống nhất kiểu code, thiết kế các object được giao những nhiệm vụ hợp lý theo phương châm “liên kết mạnh, phụ thuộc thấp “(High-Cohesion & Loose-Coupling)(Hãy đọc tập san tháng này!), đặt tên dễ hiểu cho class/method/biến số v.v.. và còn nhiều, nhiều nữa. Quan trọng là khi viết chương trình thì có đang ý thức được là cái mình đang viết đã là tài liệu quan trọng nhất đối với hệ thống hay chưa. Hãy luôn có suy nghĩ “Code chương trình này sẽ được sử dụng phổ biến như một tài liệu”

Tôi đã viết là trong code chương trình có ghi lại tất cả các thông tin hệ thống thực hiện gì (What), thực hiện như thế nào (How) nhưng nếu chỉ như vậy thì vẫn có những thông tin chưa thể truyền đạt được. Đó là “Tại sao?” (Why, hoặc là Why not), nói cách khác là lý do để đư ra một phán đoán thiết kế nào đó. Đây là nội dung mà nếu chỉ xem code chương trình thì cũng không thể hiểu được.

Các bạn có biết đến hòn đá Rossetta (Rossetta Stone) đang được trưng bày ở viện bảo Tàng Vương Quốc Anh (British Museum) ở London, Anh không? Đây chính là một bia đá nổi tiếng được coi như một phát minh quan trọng để đọc ký hiệu tượng hình (hieroglyph tiếng Ai Cập cổ đại) thông qua ghi lại cùng một đoạn văn bằng 3 ngôn ngữ.

Như tôi đã viết ở phần trước, trong giai đoạn bảo trì hệ thống phần mềm thì thông tin về việc tại sao hệ thông đang chạy lại rơi vào tình trạng như vậy (hay: tại sao lại không phải là XXX) vô cùng quan trọng. Hãy gọi những tài liệu ghi lại những thông tin nhữ vậy và là một bước đột phá trong việc hiểu hệ thống là “Rossetta Stone Document”

Figure.3 Rosetta Stone

Vậy, cụ thể thì tài liệu như thế nào mới có thể trở thành Rosetta Stone Document? Theo ý kiến của tác giả tôi thì đại khái có những tài liệu như sau.

• Ticket trên JIRA hay Redmine.
• Trang thông tin trên hệ thống Confluence hay Wiki
• Các ghi chép về trao đổi như Biên bản hội nghị (Meeting Minutes), Discussion Board
• Comment của source code
• Commit comment cho Subversion hay Git Repository

Khi viết những tài liệu này các bạn có nghĩ “Đây là tài liệu quan trọng trở thành một phần của hệ thống” hay không? Nếu không thì từ nay về sau nhất định hãy ý thức về việc này vì những người sau (trong đó có thể có cả chính bản thân bạn nữa)

Nói như vậy nhưng cũng không cần phải quy chuẩn quá. Tôi nghĩ những tài liệu quan trọng thì cần viết đúng theo format nhưng đối với những nội dung muốn để lại ở đây (Tại sao?(Why)) thì đôi khi cũng cần những thông tin mang tính chất về cảm xúc như tình huống (context) phức tạp khi đó hay những cảm xúc “hỉ nộ ái lạc” đã trải qua tại thời điểm đó. Đại tiền đề là “tính trung thực” được bảo vệ nhưng nếu cần thì viết ra tài liệu truyền tải được cảm xúc của thành viên dự án không những không có vấn đề gì mà còn phải nên viết như vậy. (Ý của tôi không phải là dùng tài liệu để đùa giỡn đâu nhé.) Hãy cùng phấn đấu vì dự án có những tài liệu mà trong đó tràn ngập nhiệt huyết và niềm vui khi phát triển của các bạn nhé

Còn có những tài liệu khác góp phần tạo nên hệ thống nữa (VD như sách hướng dẫn sử dụng (user manual) hay những tài liệu được tạo với mục đích làm hài lòng khách hàng trên phương diện kinh doanh cũng vậy). Hãy coi việc ghi nhớ 2 vấn đề sau là bài tập về nhà. Bài viết số này của tôi xin dừng tại đây. Hẹn gặp lại các bạn vào những số sau nhé.

• Source code là tài liệu quan trọng nhất!
• Hãy để lại những “Rossetta Stone Document”!

Theo tạp chí Geek and Tech, Amano-san