Hôm đó đã đủ trễ để ánh đèn văn phòng chuyển từ sáng sang mệt. Team đang chuẩn bị một release nhỏ, và có người hỏi vì sao một payment setting vẫn phải disabled ở production. Câu trả lời không nằm trong code. Không nằm trong ticket. Nó nằm trong một document ngắn được viết sáu tháng trước bởi một teammate có lẽ không biết lúc đó chúng tôi biết ơn bạn ấy thế nào.
Đó là một lý do tôi thích viết documentation. Không phải vì documentation lúc nào cũng vui, hay vì trang nào cũng tươi mới mãi. Tôi thích nó vì documentation tốt là một dạng chăm sóc thầm lặng cho công việc tương lai. Nó cho team ngày mai một điểm bắt đầu. Nó giảm số lần mọi người phải interrupt nhau chỉ để khôi phục context. Nó để codebase tự mang một phần ký ức của mình.
Trong software, mình thường ăn mừng phần nhìn thấy được: feature đã ship, architecture diagram, refactor gọn, pull request sạch. Documentation ít nổi bật hơn. Nó hiếm khi được vỗ tay trong sprint review. Nhưng sự thiếu vắng của nó thì có mặt ở khắp nơi. Người mới mất gấp đôi thời gian để hiểu một service. Production issue phải chờ trong lúc mọi người đào Slack history. Một decision bị mở lại vì không ai nhớ trade-off. Một workaround trở thành vĩnh viễn vì lý do ban đầu đã biến mất.
Documentation không cần là một manual khổng lồ. Một số doc hữu ích nhất tôi từng đọc rất nhỏ: một README giải thích cách chạy project, một ADR ghi lại vì sao team chọn queue này thay vì queue kia, một troubleshooting note cho integration hay lỗi, một example request và response ngắn, một migration checklist, một trang nói “đừng gỡ flag này cho đến khi ba customer này đã migrate.” Rõ ràng quan trọng hơn hoành tráng.
Viết doc cũng làm tư duy tốt hơn. Khi tôi cố giải thích một design bằng ngôn ngữ đơn giản, những phần mơ hồ hiện ra rất nhanh. Nếu tôi không mô tả được boundary của một module, có lẽ tôi chưa hiểu nó đủ. Nếu tôi không giải thích được khi nào dùng tool này và khi nào không nên dùng, có lẽ rule đó chưa chín. Documentation không chỉ là output sau công việc. Nó có thể là cách kiểm tra công việc có coherent hay không.
Documentation tốt tôn trọng hoàn cảnh của người đọc. Người đang đọc doc thường đang cố làm một việc gì đó dưới áp lực thời gian. Họ không cần một màn trình diễn chuyên môn. Họ cần một con đường. Đây là gì? Khi nào nên dùng? Chạy local thế nào? Có thể hỏng ở đâu? Log ở đâu? Ai own nó? Decision nào không nên vô tình đảo ngược? Một document trả lời được những câu đó đã có giá trị.
Nguy hiểm là xem documentation như một project riêng, chỉ xảy ra sau khi mọi “việc thật” đã xong. Phiên bản đó thường fail. Mọi người mệt, context đã bắt đầu phai, và doc trở nên quá rộng hoặc quá cũ. Thói quen lành mạnh hơn nhỏ hơn và gần công việc hơn: update README khi setup đổi, thêm example khi API behavior dễ nhầm, ghi lại decision khi trade-off còn mới, để lại note sau incident trước khi ký ức tan đi.
Documentation cũng có mặt xã hội. Nó làm câu hỏi beginner đỡ tốn kém hơn vì một phần câu trả lời đã được viết. Nó giúp remote và async team vì context không chỉ sống trong meeting. Nó làm ownership bớt mong manh vì trí nhớ của một người không còn là single point of failure. Nó cho những teammate ít nói một cách đóng góp khác: không phải nói nhiều nhất, mà là làm đường đi rõ hơn cho mọi người phía sau.
Tất nhiên documentation có thể cũ. Nó có thể quá dài, quá trừu tượng, hoặc quá xa code. Đó không phải lý do để né nó. Đó là lý do giữ doc gần nơi người ta dùng, xóa trang không còn giúp, và xem example như một bài test sống của sự hiểu biết. Một note nhỏ nhưng đúng tốt hơn một document bóng bẩy mà không ai tin.
Khi viết documentation, tôi hay tưởng tượng một người mệt trong tương lai, có thể chính tôi, đang cố hiểu vì sao thứ gì đó hoạt động như vậy. Tôi không cần gây ấn tượng với người đó. Tôi cần giúp họ bớt mơ hồ một chút. Nếu một document có thể biến một bí ẩn lúc đêm muộn thành năm phút kiểm tra, với tôi đó đã là lý do đủ để tiếp tục viết.