Bạn nên bao gồm những gì trong một tài liệu tiếp cận phát triển? [đóng cửa]

Tôi đang ở giữa hợp tác sản xuất một tài liệu "phương pháp phát triển" cho các nguồn lực ngoài khơi khi chúng lan tràn vào dự án của chúng tôi.

Tài liệu gần đây nhất (tương tự) mà công ty chúng tôi đã sử dụng là hơn 80 trang và không bao gồm các tài liệu tiêu chuẩn / quy ước mã hóa.

Mối quan tâm của tôi là tài liệu này sẽ không thể tiêu thụ và do đó sẽ thất bại.

Điều gì nên có trong một tài liệu tiếp cận phát triển? Có bất kỳ hướng dẫn phong nha về chủ đề này?

EDIT: Tài liệu tiếp cận phát triển nên nêu chi tiết các thực tiễn và kỹ thuật sẽ được sử dụng bởi các nhà phát triển phần mềm trong khi phần mềm được thiết kế, xây dựng và thử nghiệm.

Trong một trong những công ty mà tôi làm việc, chúng tôi có toàn bộ cách tiếp cận theo định hướng quy trình này với rất nhiều tài liệu (hầu hết trong số đó được yêu cầu điền bởi Quản lý dự án). Tuy nhiên, bất chấp độ dài và giải thích, tôi nhận ra rằng nó hầu như không được sử dụng để giúp mọi người - các nhà phát triển thực sự.

Vì vậy, tôi quyết định tự mình cố gắng với mục tiêu cụ thể là "giúp đỡ các nhà phát triển". Điều quan trọng nhất tôi bắt đầu là thu thập hầu hết các câu hỏi cơ bản - Câu hỏi thường gặp thực sự .

Điều tôi học được là việc tuân theo hầu hết mọi người khi họ muốn áp dụng quy trình nhất định và nhiều điều họ có thể không có ý tưởng trước nhưng sẽ đánh giá cao ngay lập tức nếu họ hiểu logic.

Dưới đây là các chủ đề chính mà một tài liệu như vậy sẽ giúp:

1. Quá trình phát triển để triển khai - Mã phải được tổ chức, biên dịch, xuất bản như thế nào (dưới dạng DLL, thư viện, tệp thực thi, trình cài đặt, trang web và chúng sẽ được triển khai và kiểm tra như thế nào)?

2. Làm thế nào chúng ta nên kiểm soát phiên bản? (và tại sao nếu có người mới). Hiểu cách cấu trúc của kho lưu trữ, quy tắc ứng xử - khi đăng ký có thể chấp nhận được và khi nào không, khi một phiên bản / thẻ được công bố, cách áp dụng bản vá, sáp nhập và những gì mong đợi về sự sạch sẽ khi một bản vá hoặc phát hành được tuyên bố là xong

3. Thực hiện Phương pháp luận - chúng ta có nhanh nhẹn không, chúng ta có thiết kế trước không, chúng ta sử dụng phương pháp nào? Bây giờ được đưa ra, nó có thể là một cố định cho một công ty nhất định. Bây giờ, đối với hầu hết mọi người, họ muốn biết làm thế nào chúng ta sẽ thực hiện nó cho dự án nhất định. Điều này rất cụ thể về dự án sẽ cho phép mọi người hình dung các cột mốc khác nhau và những gì có khả năng quan trọng. Trong một dự án định hướng nghiên cứu - chúng tôi muốn chỉ ra rằng "luôn xác nhận các thuật toán quan trọng trước khi xây dựng nó" trong một gói thu nhỏ tôi sẽ tập trung vào tính chính xác và tầm quan trọng của các tính năng.

4. Trách nhiệm giao tiếp - Xác định cách bạn thực hiện giao tiếp chính thức - điều này không được thực hiện với việc liệu những người cụ thể có thể nói chuyện với nhau hay không - nhưng mọi người phải có ý thức về những gì đủ quan trọng (vấn đề, quyết định thiết kế, đóng băng tính năng) để được công bố hoặc thậm chí tranh luận trước khi tiến hành thực hiện.

5. Cuối cùng, tất cả chúng ta phải có một sự hiểu biết chung về chất lượng mã, tiêu chuẩn mã hóa và nói chung những gì chúng ta cho là ổn hoặc dưới mức vệ sinh.

Tôi ước tôi sẽ bắt đầu mọi dự án với những tài liệu như vậy - tuy nhiên, nó không hoàn toàn dễ dàng. Nhưng điều quan trọng là giải quyết tất cả các vấn đề liên quan đến hành vi hàng ngày và lựa chọn của các nhà phát triển. Điều này đi một chặng đường dài khi nhiều bản phát hành ra thị trường cần được chuyển giao.

Cuối cùng, tôi cũng đề nghị rằng hãy cố gắng không chính thức nhất có thể. Thông thường, những kẻ định hướng quy trình không hoàn toàn thích các tài liệu không chính thức có khả năng bị hiểu nhầm bên ngoài bối cảnh. Tuy nhiên, nó nên được thực hiện theo cách nó kết nối các nhà phát triển.

Những gì bạn đang gọi là "tài liệu tiếp cận phát triển" thường được gọi là Kế hoạch quản lý dự án phần mềm . (Tôi cũng đã nghe nó được gọi là Kế hoạch dự án phần mềm hoặc Kế hoạch phát triển phần mềm .) Với những điều khoản đó, bạn sẽ có thể Google cho một số mẫu ngoài đó. Như Victor Hurdugaci và Donal Fellows đã đề cập, Kế hoạch quản lý dự án phần mềm bạn viết sẽ được (1) phù hợp với nhu cầu của bạn và (2) được cập nhật dưới dạng tài liệu sống khi tình hình phát triển. Điều đó đang được nói, viết một từ đầu có thể khó khăn nếu bạn chưa bao giờ viết một cái trước đó và bạn không biết những gì khác nên đi vào nó.

Có một số hướng dẫn thông qua Tiêu chuẩn IEEE 1058 (Tiêu chuẩn IEEE cho Kế hoạch quản lý dự án phần mềm, 1998). Có một bản sao của tiêu chuẩn được đăng ở đây . Tôi thấy kế hoạch này khá nặng nề, nhưng đó là một nơi tốt để lấy ý tưởng - và bạn có thể cần thêm trọng lượng nếu bạn muốn tất cả bằng văn bản cho một đội ở ngoài khơi. Ngoài ra còn có một phác thảo khá hay - và một câu chuyện tuyệt vời về cách lập kế hoạch cho các dự án phần mềm - trong một cuốn sách tôi thường xuyên chuyển sang các dự án phần mềm truyền thống (không nhanh nhẹn): Quản lý dự án phần mềm chất lượng của Futrell, Shafer và Shafer.

Một tài liệu tiếp cận là một tài liệu 'Không ở đây cũng không có' . Đây là một tài liệu thường được hỏi bởi Người quản lý dự án (Người quản lý nhà cung cấp) của các tổ chức Kinh doanh từ Người quản lý dự án (Người quản lý phát triển phần mềm) của Tổ chức phát triển ứng dụng phần mềm.

Mục đích của tài liệu này thay đổi dựa trên nhu cầu của PM Org PM.

Có thể chứa kiến ​​trúc hw, chức năng hệ thống, kế hoạch truyền thông, kế hoạch cấu hình, kế hoạch tải tài nguyên, ngăn xếp công nghệ, kiến ​​trúc ứng dụng, v.v.

một lần nữa, danh sách trên là biến dựa trên nhu cầu .. :)

Tôi chưa thấy tài liệu chính thức trên một tài liệu như vậy. nếu có bất kỳ tác giả tiêu chuẩn nào Pressman, v.v. hãy chia sẻ ..

hoặc tôi đang thiếu một cái gì đó.

Tài liệu gần đây nhất (tương tự) mà công ty chúng tôi đã sử dụng là hơn 80 trang và không bao gồm các tài liệu tiêu chuẩn / quy ước mã hóa.

Vì bạn đã có một số tài liệu, đó là điểm khởi đầu của bạn. Tự hỏi mình đi:

1. Điều gì hữu ích trong tài liệu này?
2. Điều gì còn thiếu?
3. Tại sao tôi không sử dụng tài liệu này?

Sau khi bạn nhận được câu trả lời, hãy cắt những gì không mong muốn và thêm các phần còn thiếu.

Nội dung thực tế của tài liệu phụ thuộc vào các tài nguyên có sẵn và tôi tin rằng khó có thể suy đoán bằng cách sử dụng thông tin được cung cấp.

Chỉ là một gợi ý: bạn sẽ muốn điều chỉnh tài liệu này theo thời gian vì vậy đừng viết quá nhiều;)

Thực tiễn phát triển thay đổi theo thời gian khi yêu cầu của bạn thay đổi và khi tập hợp ngôn ngữ, thư viện và khung bạn sử dụng thay đổi. Thay đổi này là không thể tránh khỏi và sẽ có nghĩa là bất cứ điều gì bạn đặt trên giấy sẽ bị lỗi thời (gần như) ngay lập tức. Cách để đối phó với điều này? Giữ tất cả trong wiki và khuyến khích mọi người trong nhóm của bạn - cả nội bộ và bên ngoài - để giúp cập nhật và liên quan.

Khi bạn đã thực hiện bước từ một tài liệu đã chết thành một tài liệu sống, cuộc tranh luận về những gì cần đưa vào trở nên ít khẩn cấp hơn: bạn chỉ cần đưa vào những gì bạn có thể nghĩ về bây giờ và quay lại vào một ngày sau đó. (Điều tốt là bạn sẽ không phải hiểu tất cả mọi thứ để viết tài liệu ở vị trí đầu tiên.) Bạn cũng có thể muốn gieo tất cả với nội dung lỗi thời từ tài liệu 80 trang cũ; điều đó sẽ cung cấp cho bạn rất nhiều tài liệu phác thảo nếu không có gì khác, giúp bạn không phải suy nghĩ về việc viết những thứ khổng lồ của những thứ nhàm chán.

Giữ tài liệu ngắn. Sử dụng cấu trúc kiểu báo - bắt đầu với chi tiết cấp cao và làm theo các chi tiết cụ thể. Thay vì bao gồm các thực hành tiêu chuẩn - chỉ cần tham khảo chúng và chi tiết sai lệch so với tiêu chuẩn.

1: Nếu bạn đã thực hiện các dự án trong công ty của mình, hãy tham gia vào quá trình đó. Thậm chí có thể ký hợp đồng phụ quản lý phát triển dự án của bạn cho họ. Đừng phát minh lại bánh xe.

2: Nếu bạn chưa phát triển nội bộ, hãy nhấn mạnh rằng nhà thầu bạn đang sử dụng có một phương pháp tốt mà họ sử dụng cho các dự án. Sau đó sử dụng phương pháp đó.

Tin tưởng nhưng xác minh. Bạn đang cố gắng loại bỏ rác trong thời gian dài. Vì vậy, đừng để họ làm bất cứ điều gì, làm theo bất kỳ quy trình nào chỉ có thể giao được vào cuối. Khăng khăng rằng có thể giao sớm được thực hiện và kiểm tra trước khi họ tiếp tục.

Ngoài ra, về cơ bản tôi rất thích trên @Dipan