Giaosucan's blog - Chia sẻ kiến thức theo cách bá đạo

Ticker

20/recent/ticker-posts

Viết code và viết doc

 Technical Documentation in Software Development: Types and Tools | AltexSoft


Di Thư Vũ Mục là cuốn sách ghi lại cách hành quân bài binh bố trận của Nhạc Phi, danh tướng đời Nam Tống. Do bị gian thần Tần Cối hãm hại, bị giam vào ngục thất, trong những năm tháng này, sợ kiến thức chiến trận của mình bị thất truyền, ông đã viết lại hết trong Di Thư Vũ Mục, với mong muốn lưu truyền cho hậu thế. Sau này Quách Tĩnh Hoàng Dung, nhờ binh pháp trong Di Thư Vũ Mục, đã giữ được thành Tương Dương khỏi quân Mông Cổ trong mấy mươi năm.


Đến cuối đời Nam Tống, quân Mông Cổ của Hốt Tất Liệt hạ thành Tương Dương, vợ chồng Quách Tĩnh Hoàng Dung tự vẫn, trước khi chết, ông đã viết lại toàn bộ pho bí kíp võ công là Cửu Âm Chân Kinh giấu trong Ỷ Thiên Kiếm, còn Di Thư Vũ Mục giấu trong Đồ Long Đao, để lại bí mật này cho con gái là Quách Tương, chưởng môn nhân phái Nga Mi sau này.

Đại Hiệp Mobile 'chào sân' bằng clip hài nghiêng ngả | GameSao

Hơn trăm năm sau, Chu Chỉ Nhược đệ tử Nga Mi lấy được Cửu Âm chân kinh và Di Thư Vũ Mục trong Kiếm, Đao luyện nên võ công đệ nhất “Cửu Âm bạch cốt trảo”, còn Di Thư Vũ Mục sau này vào tay Chu Nguyên Chương, vận dụng binh pháp đánh đuổi được quân Mông Cổ lập ra nhà Minh

Từ đó Cửu Âm Chân Kinh và Di Thư Vũ Mục được truyền từ đời này sang đời khác, sang thế kỉ 21 thì được open source trên Google và Github. Một ngày nọ, Scott Farquhar, một developer người Úc, sau khi tình cờ đọc được Cửu Âm Chân kinh trên Wikipedia bỗng ngộ ra chân lý

Từ thời xa xưa, các vị đại hiệp nếu không có ý thức viết documentation, ghi lại kiến thức kinh nghiệm của họ, thì bây giờ ta làm gì có cái để học?

Từ đó, ông hợp tác với Michael Cannon-Brookes mà lập nên https://www.atlassian.com/ một công cụ quản lý dự án và documentation gọi là Jira confluence page, workspace dự án, nơi lưu trữ tài liệu kinh nghiệm dự án.

Jira confluence giúp các nhóm lập trình trảo đổi thông tin, tài liệu, ý tưởng thuận tiện. Confluence cung cấp cho bạn khả năng để tạo ra mọi thứ, từ các ghi chú trong cuộc họp, kế hoạch dự án, yêu cầu sản phẩm, thiết kế design nhờ những plugin mạnh như drawIO, MarkDown, embedded code 

Rất nhiều các tập đoàn doanh nghiệp lớn như Digikey, Symphony đã sử dụng confluence trong việc phát triển sản phẩm của họ. Một dự án có nhiều team, mỗi team được tạo 1 space riêng và share cho các team còn lại. Những thông tin sensitive sẽ được phân quyền cho một số user. Còn kiến thức chung thì để share public cho toàn bộ team của công ty.

Một điều quan trọng của các tập đoàn này là việc các kĩ sư viết Jira documentation là điều bắt buộc và lâu dần, bên cạnh coding, viết doc đã trở thành thói quen và văn hóa của tất cả các kĩ sư trong dự án. Bao gồm từ product owner, SA cho đến developer và tester. Bất kỳ một ai cũng viết documentation, mọi nội dung từ hoành tráng vẽ vời này nọ đến lặt vặt đều welcome, miễn là hữu dụng

Việc tổ chức tài liệu trong confluence rất khoa học, được phân cấp theo level, sub-level, category để tiện cho việc tìm kiếm. Nội dung trên confluence cũng vô cùng đa dạng từ các bản thiết kế, ý tưởng, hay đơn thuần chỉ là kinh nghiệm, tip trick để giải quyết mốt vấn đề nào đó. Việc viết tài liệu được thực hiện thường xuyên, tích lũy qua năm tháng. Sau này wiki space trở thành bộ Cửu Âm Chân Kinh, ghi lại toàn bộ kiến thức của dự án, member vào sau chỉ việc lên wiki tìm kiếm thông tin là hiểu được vấn đề. Nói đơn giản thì wiki space trở thành trang “Google” của dự án.

Đấy là ở bển, nhưng ở các công ty Việt Nam thì viết document thì thật sự thảm hại. Thói quen của developer ngày nay là thích viết code hơn là viết doc, do sự yếu kém về kĩ năng trình bày, giải thích vấn đề cho người khác hiểu, tóm lại là lười viết. Một vài công ty, thì cả confluence page chỉ có một vài thanh niên viết, còn lại thì kệ. Một người viết không xuể, lâu dần thấy một mình solo mãi cũng chán, thôi giải tán. Dẫn tới có những dự án khi new member join vào chỉ biết tiếp xúc với một cục code hầm bà lằng, tả pì lù không biết bắt đầu từ đâu, gây tốn kém effort, thời gian cho người mới lẫn người cũ, khi phải giải thích training nhiều lần và lặp đi lặp lại. Trong khi nếu có wiki doc thì chỉ việc “link đó, đọc đê”

Ngoài ra nhiều dự án, lại viết doc dạng word, powerpoint rồi up lên confluence. Điều này đã mất đi tính năng hiệu quả của confluence là tìm kiếm, tổ chức nội dung (Jira không search keyword trong world, powerpoint được) biến confluence thành một kiểu Space Drive lưu file thật vô cùng lãng phí. Trong khi Jira có đầy đủ chức năng export nội dung ra word, html để thành document.

Một rào cản nữa, nhất là ở công ty outsource đó là “ngại chia sẻ do bảo mật” . Một công ty có thể có nhiều dự án, mỗi dự án sẽ có space riêng limit cho member dự án đó, rồi thân ai nấy lo, kinh nghiệm dự án nào thì dự án đó biết. Trong khi đó, mỗi dự án sẽ có kinh nghiệm, tech đặc thù, có thể bổ sung hỗ trợ lẫn nhau, dẫn tới sự trì trệ, quả là đáng tiếc. Mặc dù một vài công ty cũng hay làm kiểu “technical sharing”, seminar nhưng cái đó thì chỉ là cưỡi ngựa xem hoa, vì tâm lý “ngại nói, ngại trình bày”. Hơn nữa, một dự án long term bao nhiêu là kiến thức, đâu thể ngồi chém gió trong vòng 1 -2 tiếng là xong.

Đôi khi việc lập ra một group hỏi đáp kĩ thuật trên Team hay facebook để chia sẻ trao đổi còn hiệu quả vạn lần một buổi tech sharing với slide dài dòng lê thê, nếu như speaker không giỏi kĩ năng trình bày thì sẽ tạo cảm giác buồn ngủ, nhạt như nước ốc rồi giải tán.


Vậy thì phải làm sao

Hãy biến việc viết Jira document như một thói quen. Nó cũng giống như việc bộ GT bắt buộc đội mũ bảo hiểm khi đi xem máy. Ban đầu ai cũng khó chịu, kêu nóng, cồng kềnh như đội nồi cơm điện lên đầu. Nhưng sau, bị ép, phạt tiền, rồi đội mãi cũng thành quen. Đến giờ, thì không ai kêu ca gì nữa, lên xe là auto đội

Đăng nhận xét

0 Nhận xét