Tài liệu cho dự án?

Question

Tôi làm việc cho một công ty được chứng nhận CMMI cấp 5 và một điều tôi ghét là số lượng tài liệu mà chúng tôi chuẩn bị (Là một lập trình viên tôi đã ghét tài liệu). Chúng tôi có rất nhiều tài liệu như PID (tài liệu bắt đầu dự án), yêu cầu nghiệp vụ, yêu cầu hệ thống, thông số kỹ thuật, danh sách kiểm tra xem lại mã, nhật ký phát hành, nhật ký lỗi, kế hoạch quản lý cấu hình, danh sách kiểm tra quản lý cấu hình, tài liệu phát hành và nhiều ...

Gần 90% các tài liệu này chỉ được thực hiện vì mục đích kiểm toán QA :) .. Bạn nghĩ gì là tài liệu quan trọng nhất cho dự án? Những tài liệu nào có thể được sử dụng lâu dài bởi một nhà phát triển khác?

Vui lòng chia sẻ các phương pháp hay của bạn tại đây. Tôi muốn sử dụng chúng cho các dự án của riêng tôi hoặc công ty tôi dự định sẽ bắt đầu trong thời gian dài.

Cảm ơn

Answer 1

Các tài liệu quan trọng là một good functional spec. Nên có một và chỉ một tài liệu tham khảo cho một hệ thống.

Tài liệu lạm dụng làm tăng thêm một số lượng lớn các yêu cầu nhỏ và các tài liệu cụ thể mỗi khi ai đó thay đổi hệ thống hoặc giao diện. Đối với một hệ thống của bất kỳ phức tạp, trước khi lâu bạn có spec của bạn phân phối khoảng vài trăm loại từ, excel, visio và thậm chí cả các tập tin powerpoint. Khi điều này xảy ra, bạn sẽ mất đi sự rõ ràng về những gì hiện tại hoặc ngay cả khi bạn đã định vị và xác định tất cả các tài liệu liên quan.

Tiến trình spec BRD-SRD-Tech dựa trên giả định rằng doanh nghiệp ký tắt BRD, một nhà phân tích kinh doanh ký SRD dựa trên các yêu cầu được ghi trong BRD và đặc tả kỹ thuật được ký tắt với SRD. Điều này tạo ra một trang web đăng xuất, nhiều tài liệu với thông tin dư thừa và làm cho nó khó khăn và vụng về để giữ cho các tài liệu đặc tả được cập nhật.

Do đó, các yêu cầu tiếp theo là tài liệu có xu hướng mang hình thức của một loạt yêu cầu thay đổi và yêu cầu bổ sung và tài liệu cụ thể, mỗi tài liệu có quy trình kiểm tra và đăng xuất riêng. Bạn đạt được CYA và đường mòn kiểm toán (hoặc ít nhất là sự xuất hiện của một đường mòn kiểm toán), nhưng bạn mất đi sự rõ ràng. Hiện tại không có tài liệu tham khảo dứt khoát cho hệ thống và rất khó để thiết lập những gì hiện tại hoặc có liên quan đến bất kỳ hoạt động cụ thể nào. Kết quả là quá trình phân tích kinh doanh của bạn bị sa lầy trong nghiên cứu pháp y, điều này cho biết thêm chi phí và thời gian chờ cho lịch biểu phân phối.

Tài liệu đặc biệt phải được tạo theo cách sao cho có một tham chiếu chính xác cho bất kỳ hệ thống hoặc hệ thống phụ cụ thể nào. Tài liệu phải được cập nhật và được cập nhật. Nhận good technical documentation tool như Framemaker, để quy trình của bạn có thể mở rộng và tài liệu có một số tính toàn vẹn về cấu trúc của loại thiếu trên Word.

Answer 2

Đối với tôi, tài liệu thực sự duy nhất tôi từng sử dụng là thông số kỹ thuật. Càng chi tiết càng tốt. Tuy nhiên nó không cần phải được hoàn thành cùng một lúc, và nó không cần phải đặc biệt chính thức. Điều gì hữu ích hơn tôi nhiều hơn so với các tài liệu được kiểm tra và ký và kiểm tra kép và ký đôi là luôn luôn có thể nhận được phiên bản mới nhất của tài liệu. Và có thể nói chuyện với mọi người về những gì họ đã viết và nhận được quyết định trong trường hợp bất kỳ sự mơ hồ nào. điều này hữu ích hơn tôi nhiều hơn bất cứ điều gì khác.

Để tổng hợp: thông số là tài liệu duy nhất tôi thấy hữu ích, tuy nhiên nó có thể so sánh với người quản lý dự án biết hệ thống được đề xuất trong và có thể đưa ra quyết định hợp lý dựa trên những gì họ biết.

Answer 3

Bạn nghĩ gì là tài liệu quan trọng nhất cho một dự án?

Những người khác nhau có nhu cầu khác nhau: ví dụ: tài liệu mà chủ sở hữu cần (ví dụ: hợp đồng kinh doanh) không giống với tài liệu mà QA cần.

Các nhà phát triển khác có thể sử dụng tài liệu nào trong thời gian dài?

IMO các tài liệu quan trọng nhất (trừ mã nguồn) là đặc tả chức năng: vì những gì các phần mềm là phải làm (như trái ngược với, những gì nó được làm) là một trong những điều mà không nhất thiết phải được thiết kế ngược. Xem thêm How does a good developer keep from creating code with a low bus hit factor?

Answer 4

Stories dùng, biểu đồ burndown, mã

Answer 5

Từ quan điểm dự án trên, các tài liệu quan trọng nhất là những người bình thường bao gồm các kế hoạch từ, chẳng hạn như kế hoạch dự án, kế hoạch quản lý cấu hình, Kế hoạch chất lượng , vv

Điều bạn mô tả là phổ biến trong cải tiến quy trình và thường phản hồi lại hai nguyên nhân chính. Một là hệ thống thực sự đang nghiên cứu và tìm cách làm việc thực sự. Một câu hỏi khác thực sự được trả lời trong câu hỏi của bạn: không phải là các tài liệu chỉ được thực hiện vì mục đích kiểm tra, và tập trung của bạn không chỉ là tài liệu hữu ích cho các nhà phát triển khác mà còn cho toàn bộ dự án hoặc công ty.

Một thường nhìn vào những thứ từ quan điểm riêng của nó, đôi khi nó là cần thiết để nhìn vào bức tranh chung.

Answer 6

Tài liệu giống như đậu phụ - hầu hết mọi người ghét nó cho đến khi họ nhận ra rằng trong điều kiện thích hợp, nó có thể thực sự tốt.

Vấn đề là những gì bạn xem xét tài liệu chủ yếu được thực hiện vì mục đích của tài liệu. Bạn, với tư cách là nhà phát triển, không thấy bất kỳ giá trị trực tiếp nào trong tài liệu bạn sản xuất vì bạn biết bạn có thể thực hiện công việc của mình mà không cần tất cả các báo cáo TPS mà bạn yêu cầu.

Thật không may, tôi sẽ đặt cược rằng không có nhiều điều bạn có thể làm trong một công ty mà bạn buộc phải ăn đậu phụ thô suốt thời gian đó. Có thể bạn sẽ phải hút nó và viết các tài liệu mà công ty bạn yêu cầu, nhưng ít nhất bạn cũng có thể làm một việc ... bạn có thể viết các tài liệu ít nhất là hữu ích cho bạn và bạn có thể chuyển chúng với mã của bạn cho những người khác sẽ duy trì nó.

Ngoài tài liệu nội tuyến, bạn có thể thiết lập một wiki để sử dụng cho chính bạn và những người trong nhóm của bạn. Loại tài liệu này là có thể tìm kiếm được, đã là một điểm cộng lớn đối với các nhà phát triển, cộng với đó là một tài liệu sống thay vì một bài báo giống như bài tập về nhà bạn phải viết. Bạn đã đăng lên SO, do đó, chỉ cần nghĩ về tài liệu của bạn là tổng hợp kiến ​​thức của bạn ở một nơi hữu ích hơn.

Answer 7

Tôi là một fan hâm mộ của cái cũ 4 + 1 views:

• sử dụng Case view (tầng a/k/người dùng). Có một số hình thức: các trường hợp sử dụng thích hợp, các trường hợp sử dụng chuyển tiếp mà không được xác định rõ ràng và sử thi mà cần phải được phân hủy.

• Chế độ xem logic. Chế độ xem "tĩnh". Sơ đồ lớp UML và các sơ đồ tương tự cũng hoạt động tốt ở đây dưới dạng tài liệu thiết kế. Điều này cũng bao gồm các định dạng yêu cầu và đáp ứng cho các giao thức khác nhau. Đây là nơi chúng tôi ghi lại các yêu cầu và phản hồi RESTful. Điều này bao gồm thiết kế REST URI.

• Chế độ xem quy trình. Chế độ xem "động". Các sơ đồ hoạt động UML, sơ đồ trình tự và các biểu đồ và các thứ tương tự cho ở đây cho các tài liệu thiết kế. Trong một số trường hợp, các câu chuyện đơn giản hoạt động tốt. Trong các trường hợp khác, có một mẫu thiết kế Tiểu bang và yêu cầu phải có sự kết hợp giữa sơ đồ lớp và sơ đồ trạng thái để hiển thị cách các đối tượng trạng thái tương tác.

  Điều này cũng bao gồm các giao thức (ví dụ: REST). Đây là nơi chúng tôi xác định bất kỳ xử lý đặc biệt nào cho các yêu cầu REST khác nhau.

  này cũng bao gồm một thẩm định hay quy tắc ủy quyền, và bất kỳ khía cạnh xuyên suốt khác như an ninh, khai thác gỗ, vv

• Component xem. Các phần chúng tôi đang xây dựng để triển khai. Điều này bao gồm những thứ chúng ta phụ thuộc vào, cấu trúc của các mô đun và các gói, vv Đây thường là một sơ đồ thành phần đơn giản hoặc một danh sách các thành phần và các phụ thuộc của chúng.

• Chế độ xem triển khai. Chúng tôi cố gắng tạo mã này từ mã như được triển khai. Vì chúng tôi đang sử dụng Python, chúng tôi sử dụng epydoc để tạo tài liệu API. Chúng tôi cũng sử dụng Nhân sư để nhập tài liệu mô-đun vào chế độ xem của phần mềm này.

  Điều này cũng bao gồm thông số, cài đặt và chi tiết cấu hình.

Điều này, tuy nhiên, không đủ.

Khi dự án bắt đầu, bạn phải làm việc đến điều này thông qua một loạt các chạy nước rút.

1. Chạy nước rút đầu tiên chỉ xây dựng trường hợp sử dụng.

2. Chạy nước rút tiếp theo xây dựng một "kiến trúc" để triển khai các trường hợp sử dụng. Tài liệu kiến ​​trúc có 4 + 1 lượt xem, nhưng ở mức trừu tượng cao. Nó tóm tắt cấu trúc của các lược đồ mô hình, các yêu cầu và trả lời, xử lý RESTful, xử lý khác, thành phần dự kiến, vv Nó không bao giờ có một khung nhìn triển khai. Chúng tôi thường tham khảo tài liệu hướng dẫn của nhà điều hành và tài liệu API làm chế độ xem triển khai của kiến ​​trúc.

3. Sau đó, chạy nước rút thiết kế và xây dựng xây dựng (và cập nhật) tài liệu chế độ xem chi tiết 4 + 1 cho các thành phần khác nhau.

4. Sau đó phát hành chạy nước rút xây dựng (và cập nhật) chế độ xem triển khai.