Mọi kho mã đều có một thư mục tài liệu trông thật tuyệt vào tuần nó ra mắt. Sáu tháng sau, một nửa số trang mô tả một phiên bản sản phẩm đã không còn tồn tại, và những tính năng mới nhất thì chẳng có tài liệu nào cả.
Đây là vấn đề mang tính cấu trúc và thời gian, và hiểu được vì sao tài liệu thủ công xuống cấp theo một lịch trình có thể đoán trước chính là bước đầu tiên để thực sự cải thiện tài liệu một cách lâu dài, thay vì năm nào cũng chạy lại đúng một dự án viết lại. Dưới đây là lý do cách tiếp cận truyền thống với tài liệu cho lập trình viên thất bại ngay từ trong thiết kế, và điều gì thực sự phá vỡ vòng luẩn quẩn đó.
Vấn đề nợ tài liệu: các đội ngũ đi tới đó bằng cách nào
Nợ tài liệu vận hành giống như người họ hàng nổi tiếng hơn của nó là nợ kỹ thuật, chỉ khác ở chỗ khó nhìn thấy hơn. Một lối tắt trong mã nguồn rồi sẽ gây ra một lỗi mà ai đó phải sửa. Còn một tài liệu cũ thì cứ nằm im ở đó và sai, và không ai nhận ra cho tới khi một nhân viên mới làm theo nó và phá hỏng thứ gì đó, hoặc một ticket hỗ trợ cho thấy hướng dẫn cài đặt đã mô tả một cờ đã bị loại bỏ suốt bốn tháng.
Diễn biến gần như luôn giống nhau. Khi ra mắt, tài liệu rất đầy đủ vì đội ngũ có động lực và phạm vi sản phẩm còn nhỏ. Ba tháng và năm bản phát hành tính năng sau đó, hai trong số các tính năng ấy đã có tài liệu, ba tính năng còn lại chỉ tồn tại trong đầu những người đã xây dựng chúng. Đến khi có ai đó rà soát lại tài liệu, khoảng cách giữa những gì được viết ra và những gì đúng đã lớn tới mức việc sửa chữa trông giống như một dự án chứ không phải một thói quen.
Đây cũng không phải là một chi phí giả định. Nghiên cứu của Stack Overflow cho thấy tài liệu đã ngốn khoảng 11% số giờ làm việc của lập trình viên, và GetDX ước tính rằng các kỹ sư mất 3-10 giờ mỗi tuần để săn tìm thông tin lẽ ra đã phải được ghi lại, những giờ không hề xuất hiện trên roadmap nhưng vẫn biến mất khỏi kết quả công việc thực tế.
Vì sao tài liệu thủ công luôn tụt lại phía sau quá trình phát triển
Thay đổi mã nguồn thì rẻ để thực hiện nhưng đắt để ghi tài liệu. Một bản sửa một dòng cho bộ giới hạn tốc độ có thể chỉ mất năm phút để viết và phát hành, nhưng giải thích nó một cách chính xác, cái gì đã thay đổi, vì sao, và điều đó có nghĩa gì với bất kỳ ai gọi endpoint đó, lại đòi hỏi thời gian viết thực sự, không bị ngắt quãng, thứ sẽ không tồn tại trong một sprint vốn đã đầy những cam kết khác.
Mỗi commit là một điểm quyết định nhỏ và lặng lẽ. Phải có ai đó nhận ra thay đổi này đủ quan trọng để ghi tài liệu, ghi nhớ nó, rồi tìm thời gian để làm. Tài liệu thủ công phụ thuộc vào việc cả ba điều đó xảy ra một cách nhất quán, với mọi thay đổi quan trọng. Chỉ cần một điều thỉnh thoảng thất bại là nợ tài liệu bắt đầu chất đống.
Niềm tin rằng mã nguồn sạch thì nên tự giải thích cũng không giúp gì. Những hàm được đặt tên tốt và logic rõ ràng giải thích mã nguồn làm gì cho một người đã thông thạo kho mã đó. Nó không giải thích vì sao, vì sao lại là cái này, cách sử dụng nó, hay nó khớp vào hệ thống lớn hơn như thế nào. Đó chính xác là loại thông tin mà tài liệu thủ công được cho là phải cung cấp, và cũng chính xác là loại thông tin bị bỏ qua khi thời gian eo hẹp.
Sẵn sàng phát triển doanh nghiệp của bạn?
Bắt đầu dùng thử miễn phí ngay hôm nay và xem kết quả trong vài ngày.
3 nguyên nhân gốc rễ khiến tài liệu lập trình viên thiếu sót
Bên dưới lời phàn nàn chung chung rằng “tài liệu của chúng tôi kém” là ba cơ chế cụ thể, có thể sửa được:
- Quyền sở hữu bị phân tán. Khi tài liệu là “trách nhiệm của mọi người”, thì thực tế nó không là trách nhiệm của ai cả. Không có một người hay một tác nhân kích hoạt cụ thể chịu trách nhiệm cập nhật một tài liệu cụ thể, việc đó mặc định rơi vào bất kỳ ai tình cờ nhận ra nó sai, thường là một nhân viên mới đang bối rối hoặc một khách hàng đang bực bội. Thêm vào đó, cách tiếp cận này còn lan truyền định dạng, ngôn ngữ và phong cách viết không nhất quán.
- Chi phí không cân xứng. Viết một thay đổi thì nhanh hơn viết một lời giải thích chính xác về thay đổi đó cho người khác. Dưới bất kỳ áp lực thời hạn nào, công việc cạnh tranh trực tiếp với việc phát hành mã nguồn sẽ thua.
- Không có cơ chế kích hoạt. Hầu hết các đội ngũ không gắn việc cập nhật tài liệu với một sự kiện cụ thể như một pull request đã được hợp nhất hay một bản phát hành. Không có tác nhân kích hoạt đó, tài liệu chỉ được xử lý một cách thụ động, sau khi một ticket hỗ trợ hay một lần onboarding thất bại buộc phải giải quyết, nghĩa là việc sửa chữa luôn đến sau khi chi phí đã bị trả.
Cách AI thu hẹp khoảng cách giữa mã nguồn và tài liệu
Một trình viết tài liệu AI giải quyết trực tiếp ba nguyên nhân này, vì nó thay đổi bài toán kinh tế thay vì yêu cầu mọi người phải hành xử khác đi trong cùng những ràng buộc cũ.
AI Documentation Writer của FlowHunt hoạt động qua ba giai đoạn . Đầu tiên nó phân tích mã nguồn, sau đó chuyển dịch logic, và cuối cùng cấu trúc hóa tài liệu đầu ra. Bạn cung cấp mã nguồn, ngôn ngữ chính, mục đích, đối tượng độc giả mục tiêu, và bất kỳ thông tin bổ sung nào bạn thấy phù hợp hoặc mà biểu mẫu yêu cầu.
Tài liệu được tạo ra sau cùng bao gồm tóm tắt điều hành, các năng lực chức năng, kiến trúc kỹ thuật, luồng logic, các hàm và thành phần chính, và hướng dẫn sử dụng.
Quá trình đó sửa trực tiếp vấn đề chi phí không cân xứng. Nếu việc tạo lại tài liệu chính xác từ mã nguồn hiện tại chỉ mất vài phút thay vì nửa ngày viết cẩn thận, nó không còn thua trong cuộc cạnh tranh ưu tiên với việc phát hành mã nguồn nữa.
Nó cũng làm suy yếu vấn đề sở hữu, vì một quy trình nhanh, ít công sức là thứ thực tế có thể giao cho người hợp nhất thay đổi, thay vì mỗi lần đều phải kéo một người viết chuyên trách vào. Việc lấy bớt khỏi tay người viết những công việc nhỏ nhưng tốn thời gian cũng cho phép họ chăm chút hơn cho những nội dung quan trọng.
Cơ chế kích hoạt vẫn cần được thiết kế có chủ đích. FlowHunt không tự theo dõi kho mã của bạn, nhưng vì đây là một nền tảng tự động hóa quy trình, flow có thể được nối với một webhook kích hoạt mỗi khi một pull request có đụng tới module được ghi tài liệu được hợp nhất.
Tham gia bản tin của chúng tôi
Nhận các mẹo, xu hướng và ưu đãi mới nhất miễn phí.
Xây dựng một hệ thống tài liệu luôn cập nhật
Một hệ thống tài liệu tồn tại được qua vài tháng đầu tiên cần nhiều hơn một bước tạo sinh nhanh. Một vòng lặp khả thi trông như sau:
Kích hoạt. Một pull request đã được hợp nhất hoặc một lần cắt bản phát hành đưa mã nguồn liên quan vào trình viết tài liệu, với đối tượng độc giả và mục đích được đặt cho đúng loại tài liệu đó (một tham chiếu API, một hướng dẫn người dùng, một quy trình chuẩn nội bộ).
Ghi lại những gì không nằm trong mã nguồn. Một số ngữ cảnh không bao giờ đi vào mã nguồn, chẳng hạn vì sao một script triển khai lại hoạt động theo cách đó, điều thường chỉ tồn tại dưới dạng lời giải thích miệng của một kỹ sư. Luôn hữu ích khi đưa thông tin này vào công cụ cùng với chính mã nguồn. Lời giải thích bổ sung thêm ngữ cảnh và chiều sâu, đảm bảo nội dung được tạo ra mang tính con người và cụ thể hơn.
Đối chiếu ngữ cảnh bên ngoài khi cần. Kiểm tra mọi tiêu chuẩn, giao thức hay quy ước trong ngành đáng để xác minh với các nguồn bên ngoài. Đồng thời kiểm tra lại dữ liệu độc quyền mà bạn đưa cho AI, vì nó có thể đã lỗi thời.
Rà soát trước khi xuất bản. Một người hiểu hệ thống xác nhận các bước cài đặt thực sự chạy được, kiểm tra rằng mọi phần cũ mà AI không thể suy ra chỉ từ mã nguồn được mô tả chính xác, và xác minh rằng kết quả đọc đúng với đối tượng độc giả mục tiêu.
Kích hoạt lại ở thay đổi tiếp theo. Bạn có thể thiết lập việc tạo lại theo lịch hoặc qua một tác nhân kích hoạt tùy chỉnh. Ví dụ, bạn có thể cho vòng lặp lặp lại ở lần hợp nhất tiếp theo, đó là cách tốt nhất để giữ khoảng cách giữa mã nguồn và tài liệu luôn nhỏ.
Tài liệu lập trình viên tốt thực sự trông như thế nào
Tài liệu tốt không được định nghĩa bằng độ dài hay sự trau chuốt, nó được định nghĩa bằng việc liệu nó có trả lời những câu hỏi mà người đọc thực sự có, theo đúng thứ tự họ sẽ hỏi. Một cấu trúc hữu ích bao gồm:
- Nó làm gì — một tóm tắt ngắn về mục đích và phạm vi, để người đọc có thể biết trong một đoạn văn liệu họ có đang ở đúng chỗ không.
- Nó cho phép làm gì — những năng lực và tính năng cụ thể, không chỉ là diễn giải lại mã nguồn.
- Nó được xây dựng thế nào — đủ ngữ cảnh kiến trúc (stack, thành phần, phụ thuộc) để ai đó có thể suy luận về hệ thống, chứ không chỉ sử dụng nó.
- Nó hoạt động ra sao — luồng logic và các thao tác chính, được giải thích như một quy trình chứ không phải một danh sách tên hàm.
- Cách sử dụng nó — hướng dẫn cài đặt, cấu hình và sử dụng được viết cho chính người đọc thực sự, không phải cho người đã viết mã nguồn.
Đây cũng không phải ngẫu nhiên mà gần với những gì một quy trình tạo sinh bám sát mã nguồn tạo ra một cách tự nhiên, vì mỗi phần tương ứng với một câu hỏi mà người đọc thực sự đặt ra, chứ không phải một mục mà người viết cảm thấy có nghĩa vụ phải đưa vào.
Từ nợ tài liệu tới tài sản tài liệu
Nợ tài liệu và tài liệu như một tài sản là cùng một nguyên liệu nền tảng, mã nguồn và tri thức tổ chức, chỉ ở hai mức chi phí bảo trì khác nhau. Khoảnh khắc việc tạo lại một tài liệu trở nên đủ rẻ để làm ở mọi thay đổi có ý nghĩa, chính thông tin từng mục ruỗng thành nợ sẽ bắt đầu tích lũy thành thứ mà cả đội ngũ có thể dựa vào.
Bắt đầu viết tài liệu tốt hơn với AI và xem bao nhiêu phần trong khoản nợ tài liệu hiện tại của bạn thực ra chỉ là một bài toán chi phí đang chờ một quy trình nhanh hơn.
Để hiểu đầy đủ cơ chế của quá trình tạo sinh bên dưới, xem cách viết tài liệu kỹ thuật tự động bằng AI , và với những loại tài liệu cụ thể mà cách tiếp cận này xử lý tốt, xem năm loại tài liệu AI viết nhanh hơn .
