Chính xác những gì bao gồm 'Tài liệu'?

Khi chúng tôi nói 'tài liệu' cho một sản phẩm phần mềm, bao gồm những gì và không nên bao gồm những gì?

Ví dụ, một câu hỏi gần đây được hỏi nếu ý kiến ​​được coi là tài liệu?

Nhưng có nhiều lĩnh vực khác mà đây cũng là một câu hỏi hợp lệ, một số rõ ràng hơn những lĩnh vực khác:

• Hướng dẫn sử dụng (rõ ràng)
• Ghi chú phát hành?
• Hướng dẫn
• Bình luận
• Bất kì thứ khác?

Đâu là đường vẽ. Ví dụ: nếu 'hướng dẫn' là tài liệu, là tài liệu 'video hướng dẫn', hay nó là cái gì khác?

Nói chung, một cái gì đó trong phần mềm không 'hoàn thành' cho đến khi nó được triển khai, thử nghiệm và ghi lại. Do đó, câu hỏi này, những điều chúng ta nên xem là một phần của tài liệu để xem xét một cái gì đó 'được thực hiện'.

_{Câu hỏi truyền cảm hứng từ phản hồi của khách hàng gần đây tại hội nghị của chúng tôi cho thấy rằng tài liệu của chúng tôi cần nhiều 'mẫu' hơn, mà trước đây chúng tôi đã không xem xét tốt như chúng tôi nên có.}

_{Đối tượng: Các nhà phát triển phần mềm sử dụng (các) cơ sở dữ liệu, ngôn ngữ lập trình và công cụ liên quan của chúng tôi (chẳng hạn như ứng dụng khách quản trị cho DB)}

Mục tiêu của tài liệu là mô tả và giải thích sản phẩm phần mềm, do đó bạn có thể định nghĩa tài liệu là tập hợp các vật phẩm đóng góp cho mô tả hoặc giải thích đó. Bạn có thể không coi các hành động liên quan là một phần của tài liệu: ví dụ: khóa đào tạo kéo dài một tuần không phải là tài liệu mà là tài liệu khóa học; một cuộc trò chuyện bảng trắng năm phút không phải là tài liệu mà là một hình ảnh của bảng trắng.

Giữ mục tiêu (giải thích phần mềm) trong tâm trí, tài liệu được hoàn thành khi khách hàng hài lòng với lời giải thích : giống như phần mềm kết thúc khi khách hàng hài lòng với phần mềm. Hãy nhớ rằng khách hàng cho tài liệu không phải lúc nào cũng giống như khách hàng trả tiền cho phần mềm: nhân viên hỗ trợ, người kiểm tra, nhân viên bán hàng và những người khác sẽ cần một số hiểu biết về phần mềm làm gì và cách thức hoạt động của phần mềm.

Điều này giúp hiểu ranh giới của bạn cho những gì nên được bao gồm trong tài liệu nằm. Sử dụng "trình đọc" như một cách viết tắt tiện lợi, mặc dù chúng tôi chấp nhận rằng có thể bao gồm video hoặc âm thanh: mọi thứ giúp người đọc có được thông tin họ cần về phần mềm là tài liệu họ có thể sử dụng, mọi thứ khác đều không. Nếu khách hàng của bạn cần thông tin chi tiết về tất cả các trường hợp sử dụng của họ, thì đó cần phải là một phần của tài liệu. Các nhà phát triển của bạn có thể cần mã nguồn, thông tin về kho lưu trữ kiểm soát phiên bản của bạn và hướng dẫn xây dựng: đó là tài liệu cho họ, nhưng như được mô tả ở trên, nó sẽ không phải là một phần của tài liệu của khách hàng.

Tôi nghĩ rằng bạn đã lấy đi phần sai từ cuộc trò chuyện của bạn tại một hội nghị. Các phương pháp phát triển phần mềm hiện đại ủng hộ rằng nhóm phát triển nên làm việc chặt chẽ với khách hàng của mình (hoặc chủ sở hữu sản phẩm đóng vai trò là proxy khách hàng). Đối với tất cả các công việc được giao, định nghĩa "hoàn thành" là điều được đàm phán giữa nhóm và khách hàng của mình và được thực hiện trên cơ sở định kỳ khi phần mềm đang được phát triển.

Vấn đề bạn gặp phải là bạn có sự mất kết nối giữa những gì bạn cho là khách hàng cần và những gì họ mong đợi bạn sẽ cung cấp để cuối cùng bạn nhận được sự ngạc nhiên "hey tất cả các mẫu".

Theo như, tài liệu là gì ... tốt, nó gần như là tất cả những gì bạn đã liệt kê và có thể vài điều nữa mà bạn đã không làm. Nhưng không ai có thể cho bạn biết dự án của bạn cần bao nhiêu tài liệu. Mỗi dự án là khác nhau và tùy thuộc vào nhóm của bạn, chủ sở hữu sản phẩm và khách hàng của bạn để xác định mức độ và loại tài liệu cần thiết cho dự án của bạn.

Một số yếu tố sẽ được sử dụng:

• Bạn đang phát triển phần mềm v1.0 và họ đang chuyển sang các dự án khác hay đây là dự án dài hạn đang thực hiện? Nhận xét / tài liệu thiết kế trở nên quan trọng hơn nhiều trong trường hợp sau. Mặt khác, nếu khách hàng của bạn là một cửa hàng bánh rán mẹ và bạn đang viết một trang web cho họ mà bạn sẽ không bao giờ nhìn thấy ... tôi đoán tài liệu mã là tốt nhưng không quan trọng.
• Bạn đang phát triển một trò chơi hoặc phần mềm di động đang điều khiển máy đo nhịp tim trong bệnh viện. Đoán xem ai sẽ có định nghĩa về "thực hiện" có nhiều tài liệu hơn?
• Khách hàng của bạn là người dùng cuối điển hình hay họ là nhà phát triển khác? Bạn có API / SDK mà bạn đang phơi bày không?
• Trình độ chuyên môn của khách hàng của bạn là gì? Điều này ảnh hưởng đến việc lựa chọn video hướng dẫn so với tài liệu bằng văn bản so với một số loại ứng dụng hướng dẫn tương tác
• Làm khách hàng của bạn quan tâm về những gì thay đổi từ phiên bản sang phiên bản. Một số làm. Hầu hết không. Đối với một số ít đó là luật (hoặc gần như vậy) để quan tâm.

Tài liệu là thứ dự định được đọc mà không sửa đổi nó.

Tôi nghĩ bạn không thể sai với định nghĩa dựa trên mục đích ... nhưng chỉ khi bạn xác định đúng mục đích.

• ^{Xác định đúng mục đích tài liệu không hoàn toàn đơn giản. Sự khác biệt đơn giản (ngây thơ nếu bạn muốn) xuất hiện một cách tự nhiên là tài liệu là mọi thứ dành cho việc đọc - trong khi, để so sánh, mã là bất cứ thứ gì dành cho thực thi máy tính . Nghe có vẻ hay đấy chứ? nhưng nó thực sự trở nên khá xấu xí khi bạn đào sâu hơn.
   
  Điều quan trọng là, mã tốt sẽ tính đến các mối quan tâm về khả năng đọc, cùng với tính chính xác của việc thực thi - điều này làm cho sự khác biệt "dễ đọc" trở nên vô dụng trong việc xác định tài liệu.
   
  Các mẫu mà bạn đề cập cho thấy có gì sai với nó. Khách hàng thường mong đợi những điều này được viết rõ ràng vàthực hiện đúng. Thỏa hiệp về khả năng đọc hoặc tính chính xác có thể mang lại một loạt các khiếu nại của khách hàng. Phân biệt ngây thơ không giúp tìm hiểu xem các mẫu là mã hoặc tài liệu.
   
  Sử dụng sự phân biệt ngây thơ sẽ còn rắc rối hơn nữa nếu bạn tưởng tượng làm việc với nguồn mở . Bạn tải xuống, xây dựng và chạy nó - bạn không đọc nó, đó chỉ là mã phải không? Đợi đã, mọi thứ đã sai và bạn lấy mã để đọc những gì đang diễn ra ở đó ... này bạn đọc không thực thi - tài liệu này có phải bây giờ không? Và cuối cùng, bạn tìm thấy lỗi trong nguồn và sửa nó - bây giờ đây thực sự là mã, nó không phải là thứ thường được gọi là tài liệu, bất kể bạn đọc nó cẩn thận đến mức nào để sửa nó.}

Đối với 'mẫu' bạn sẽ cung cấp, phân biệt đọc không sửa đổi có thể trở nên khá quan trọng.

Hãy xem, nếu một số mẫu bị lỗi khi chạy không thay đổi, trong môi trường tham chiếu tài liệu, đó là lỗi của bạn - lỗi trong tài liệu của bạn, một lỗi bạn phải chấp nhận và sửa chữa, tốt thôi.

Bây giờ, nếu có vấn đề với mẫu hoặc môi trường đã sửa đổi, đó không phải là lỗi của bạn nữa - ý tôi là không có lỗi trong tài liệu, vì tài liệu không nhằm mục đích sửa đổi. Bất cứ điều gì giúp bạn cung cấp cho người dùng trong trường hợp như vậy, sẽ thuộc danh mục hỗ trợ, không phải là lỗi.

Bất cứ điều gì trả lời câu hỏi "làm thế nào để tôi ..." là tài liệu.

Đối với các nhà phát triển, điều đó có nghĩa là các đặc tả yêu cầu ("làm thế nào để tôi biết phải viết gì"), tài liệu thiết kế ("làm thế nào để tôi giải quyết các yêu cầu của tôi"), ma trận truy xuất nguồn gốc ("làm thế nào để tôi biết rằng thiết kế của tôi đáp ứng tất cả các yêu cầu của tôi"), kế hoạch kiểm tra ( "làm thế nào để tôi biết tác phẩm mã của tôi"), kiểm tra đơn vị ( "làm thế nào để tôi biết tôi đã yêu cầu safisfied X"), ý kiến inline ( "làm thế nào để đảm bảo schlub nghèo tiếp theo hiểu lý do tại sao tôi đã viết nó này cách "), hướng dẫn triển khai (" làm cách nào để đóng gói sản phẩm này để cài đặt "), v.v.

Đối với người dùng, điều đó có nghĩa là hướng dẫn sử dụng ("cách tôi sử dụng phần mềm"), hướng dẫn ("làm cách nào để sử dụng tính năng cụ thể này"), ghi chú phát hành ("làm cách nào để biết lỗi nào đã được sửa / tính năng lỗi mới đã được sửa đã thêm "), v.v.