Viết tài liệu như thế nào là đủ và khi nào nên viết? - Từ quan điểm Agile

Không biết bạn có nằm lòng các giá trị của Agile Manifesto không?

Individuals and interactions over processes and tools

Working software over comprehensive documentation.

Customer collaboration over contract negotiation

Responding to change over following a plan

Mặc dù Agile manifesto đề cập đến từ documentation, nhưng các nguyên tắc agile lại không đưa ra bất kỳ chỉ dẫn cụ thể nào về cách để làm tài liệu.

Như vậy có phải áp dụng Agile là không cần có tài liệu nữa không?

Không phải như vậy.

Vì không quy định cụ thể nên chúng ta cần tư duy về mục đích của việc tài liệu hóa là gì, mang lại giá trị gì, để có cách tiếp cận phù hợp.

Cũng có thể hiểu là tùy dự án, tùy tình huống mà chúng ta sẽ có những cách tiếp cận, xử trí khác nhau và linh hoạt để mang lại giá trị nhiều nhất cho khách hàng, và người sử dụng.

Liên quan đến chủ đề này, gần đây mình có tìm hiểu thêm các quan điểm của các chuyên gia về Agile trong ngành phần mềm và tổng hợp tại đây. Mong là các quan điểm này sẽ giúp bạn hình thành cho bản thân những cách tiếp cận linh hoạt và nhẹ nhàng khi bước vào nhiệm vụ viết tài liệu.

Ester F.Goncalves - Documenting theo Agile mindset

Nguyên lý đằng sau agile mindset là tập trung vào chuyển giao giá trị cho khách hàng. Điều đó có nghĩa là chúng ta sẽ sử dụng phần lớn thời gian để phát triển sản phẩm mang lại giá trị cho khách hàng, tránh tốn công sức vào những task không gia tăng thêm giá trị gì. Nguyên tắc này cũng áp dụng với việc documentation/ làm tài liệu.

Theo cách tiếp cận Waterfall - thác nước, documentation là bước được ấn định trước và tốn nhiều thời gian công sức để hoàn thành, sau documentation, mới chuyển sang bước thực hiện phát triển sản phẩm. Khi chuyển sang cách làm agile, chúng ta cần phải tư duy lại về cách chúng ta làm tài liệu, tránh tốn thời gian vào sản phẩm chuyển giao mà không biết dùng để làm gì.

Một nguyên lý nữa của agile là thích nghi với sự thay đổi. Tức là chúng ta không nên lập kế hoạch quá nhiều trước khi làm vì mọi thứ đều có thể thay đổi trong khi dự án diễn ra. Do đó nên tập trung vào just-in-time planning. Tương tự với việc làm tài liệu, tránh tốn thời gian, chỉ làm tài liệu khi và chỉ khi thật cần thiết.

Để tránh tốn công sức vào việc viết tài liệu mà không ai đọc, hãy hỏi mọi người các câu hỏi:

• Tài liệu này dùng vào việc gì? Hỗ trợ việc phát triển sản phẩm? Hay cung cấp thông tin tham khảo về mặt kỹ thuật?
• Ai là đối tượng đọc của tài liệu? Họ ở phòng ban nào? Hay là khách hàng? Hay cho đội bảo trì tương lai?
• Các đối tượng người đọc sẽ sử dụng tài liệu này ra sao? Dùng tham khảo? Dùng làm hướng dẫn sử dụng thực tế?
• Việc viết tài liệu này tốn bao nhiêu chi phí? Mất bao lâu để làm tài liệu này? Ai sẽ cần tham gia viết?

Đặt những câu hỏi như thế giúp bạn xác định được có cần phải viết tài liệu này hay không. Just enough - chỉ vừa đủ, không thừa, không thiếu, mà đánh vào chính xác nhu cầu của các stakeholders và làm ra tài liệu họ cần.

Ashish - Cân bằng giữa documentation và discussion

Ashish Sharma đề cập đến việc cân bằng giữa documentation và discussion.

“Trong agile, chúng ta cần phải tìm được điểm cân bằng giữa tài liệu hóa và trao đổi tương tác giữa các thành viên. Tài liệu hóa là một phần của mọi hệ thống, nhưng tài liệu đầy đủ và hoàn chỉnh không đảm bảo thành công của dự án.”

"Có 3 tiêu chí bạn cần sử dụng để xác định xem viết tài liệu như thế nào là đủ, và khi nào thì nên viết

• Tính cần thiết - Essential: Tài liệu với mô tả chi tiết đủ dùng
• Giá trị - Valuable : Soạn tài liệu chỉ khi chúng ta cần để dùng trong thực tế, chứ không phải khi chúng ta muốn có một thứ để đấy.
• Đúng thời điểm - Timely: Soạn tài liệu được thực hiện theo phong cách Just in time - vừa đúng lúc, khi chúng ta cần. "

Mario Moreira - Right-sizing documentation

Mario Moreira nói về right-sizing documentation trong thế giới Agile.

Right-sizing có nghĩa là nỗ lực để viết và duy trì, giữ gìn tài liệu cộng với giá trị của tài liệu được viết ra cần có tỷ lệ ROI lớn hơn so với tình trạng không sẵn có thông tin về quy trình đó

Một số điểm mà ông này gợi ý:

• Tài liệu cần phải “sống” và tiến hóa, chứ không phải để đấy. Hãy bỏ ra khỏi đầu khái niệm “bản cuối cùng - final”
• Quá trình soạn tài liệu nên có yếu tố cộng tác. Tài liệu không nên được viết bởi chỉ 1 người từ đầu đến cuối rồi mới chia sẻ với người khác. Thay vào đó, chia sẻ thường xuyên từ lúc còn là bản nháp để đón nhận những góp ý, đóng góp của mọi người.
• Tập trung vào viết tài liệu vừa đủ tốt (Barely good enough), tránh những chi tiết to đùng ngay từ đầu (big upfront), tốn nhiều công sức và đòi hỏi phải đoán trước. Barely good enough nghĩa là chỉ viết ra những gì bạn hiện đang biết.
• Cập nhật tài liệu liên tục khi bạn và team học được điều mới. Khi bạn khám phá ra những thứ giúp team tốt hơn hoặc hỗ trợ quá trình ra quyết định, hãy document và cập nhật tài liệu.
• Tài liệu có thể ở nhiều dạng. Dạng word, hay trên wiki, thậm chí là comment trong code.

Tom de Lancey - Emergent Documentation

Tom de Lancey nói về cách tiếp cận Emergent Documentation

“… chúng ta không muốn tốn thời gian, công sức để viết tài liệu những thứ chúng ta còn chưa làm. Hãy tài liệu hóa những thứ chúng ta thực sự ĐÃ LÀM, chứ không phải thứ chúng ta nghĩ chúng ta sẽ làm.”

Một trong những lợi ích của cách tiếp cận này là việc soạn tài liệu sẽ trở thành 1 phần của quá trình phát triển, chứ không là hoạt động tách rời. Hiểu được tầm quan trọng của việc lưu lại tài liệu, cả team sẽ có hứng thú làm nó và giữ gìn nó. Mỗi story sẽ có 1 task đi kèm là cập nhật WIKI (một trang web kết nối các story lại với nhau).

Michael Nygard - Begin with the end in mind

Michael Nygard gợi ý bạn nên đứng từ quan điểm của người tiêu dùng tài liệu, bắt đầu với điểm kết thúc trong đầu (begin with the end in mind):

" Tôi thường không thấy các quy trình có người sử dụng. Thật là lãng phí. Hầu như không ai cần sản phẩm đầu ra của quy trình nhưng người tạo ra quy trình chẳng hề nhận ra điều đó."

Michael cũng gợi ý bạn nên đặt những câu hỏi như:

1. Who is the consumer? - Người tiêu dùng của bạn là ai?

2. What do they need? - Họ đang cần gì?

3. How do you deliver it to them? - Bạn chuyển giao tài liệu tới họ như thế nào?

4. How do you know when they’re ready for it? - Làm sao bạn biết khi nào họ sẵn sàng dùng tài liệu?

5. How do you produce it? - Bạn sẽ sản xuất tài liệu như thế nào?

6. What inputs do you need to produce it? - Bạn cần những đầu vào gì để sản xuất ra tài liệu đó?

--------

Nguồn tham khảo:

A Roadmap to Agile Documentation

Documentation in Agile: How much and When to write it?

Right-sizing documentation in an Agile World

‍