Một tài liệu thiết kế nên chứa một cuộc thảo luận về những ưu / nhược điểm đối với một thiết kế nhất định hay nó nên tập trung vào các sự kiện và lý do?

Tôi hiện đang trong quá trình cập nhật tài liệu thiết kế để nó chính xác và cập nhật cho các nhà phát triển trong tương lai.

Hiện tại, tài liệu chỉ tập trung vào các sự kiện, trình bày cách thiết kế. Không có lý do cho bất kỳ quyết định được trình bày. Tôi tin rằng điều quan trọng là phải nắm bắt được lý do để các nhà phát triển biết tại sao mọi thứ lại diễn ra như vậy, vì điều đó có thể sẽ ảnh hưởng đến các quyết định trong tương lai. Tôi không thể thêm lý do cho tất cả các quyết định thiết kế, đặc biệt là những quyết định được đưa ra trước khi tôi bắt đầu thực hiện dự án, nhưng tôi đang làm những gì có thể trong bộ phận này.

Tuy nhiên, một số quyết định thiết kế, tôn trọng, quyết định rất kém đưa ra các yêu cầu của dự án. Có một số người tốt, mặc dù, là tốt.

Suy nghĩ ban đầu của tôi là tôi nên bao gồm một cuộc thảo luận về các vấn đề thiết kế và các giải pháp tiềm năng hoặc giải pháp cho các vấn đề này để tập trung sự chú ý của các nhà bảo trì trong tương lai, nhưng tôi không chắc liệu tài liệu thiết kế có phải là nơi dành cho loại thảo luận và thông tin này không. Tôi không muốn một "nhà phê bình" thiết kế ném bóng tuyết thành "xé toạc thiết kế này một cái mới" vì những người khác làm việc trên hệ thống này và cập nhật tài liệu, vì điều đó rõ ràng không phù hợp.

Người quản lý của tôi sẽ ủng hộ một trong hai quyết định, vì vậy nó tùy thuộc vào tôi. Bất kể cách tiếp cận nào tôi thực hiện, tài liệu được tạo ra sẽ được chính thức phiên bản và cung cấp cho các nhà phát triển làm việc trên hệ thống, thường là trước khi họ được giao nhiệm vụ phát triển. Chúng tôi hy vọng rằng một nhà phát triển mới sẽ tự làm quen với các tài liệu được liên kết với một hệ thống phần mềm nhất định trước khi bắt đầu công việc phát triển.

Câu hỏi:

• Một tài liệu thiết kế nên bám sát các dữ liệu thô ("đây là thiết kế") và lý do ("đây là lý do tại sao đây là thiết kế") hay nó cũng nên được sử dụng để chỉ ra các vấn đề không bị lỗi với thiết kế có thể gây ra sự cố nhà phát triển trong tương lai?
• Nếu tài liệu thiết kế không nên được sử dụng để nắm bắt thông tin này, loại tài liệu nào nên nắm bắt nó và những gì khác cần được nắm bắt với một cuộc thảo luận về các lý do thiết kế, sự đánh đổi và các vấn đề đã biết (không phải là lỗi, vì các khiếm khuyết được theo dõi sử dụng các công cụ khác)?

Nếu những ưu và nhược điểm có thể được tóm tắt trong một hoặc hai câu, thì bạn có thể đưa chúng vào tài liệu thiết kế. Bất cứ điều gì lâu hơn nên được tách ra.

Nơi tôi hiện đang làm việc, thường có một tài liệu "Thiết kế quyết định" riêng để theo dõi tất cả các quyết định quan trọng và quan trọng. Thường được định dạng bằng một đoạn mô tả sự cố (chẳng hạn như "Một số tệp cần được chuyển từ máy chủ đến một số người dùng ở cuối mỗi chu kỳ xử lý, có nhiều cách để làm điều này ..."), một bảng có các cột " mô tả giải pháp "(chẳng hạn như" di chuyển tệp qua FTP ")," ưu "(chẳng hạn như" Dễ quản lý người dùng ")," khuyết điểm "(chẳng hạn như" không đủ an toàn để tuân thủ ABC-XYZ ") và kết luận rằng giải thích tại sao một quyết định cụ thể được chọn (chẳng hạn như "FTP sẽ không được sử dụng vì nó sẽ không thể đáp ứng các yêu cầu tuân thủ nhất định"). Tài liệu thiết kế thường chỉ tham chiếu quyết định đã chọn,

Một tài liệu thiết kế nên bám sát các dữ liệu thô ("đây là thiết kế") và lý do ("đây là lý do tại sao đây là thiết kế") hay nó cũng nên được sử dụng để chỉ ra các vấn đề không bị lỗi với thiết kế có thể gây ra sự cố nhà phát triển trong tương lai?

Đó không phải là "hoặc - hoặc".

Không ai đọc tài liệu ở nơi đầu tiên. Họ lướt qua - tốt nhất. Do đó, viết càng ít tài liệu càng tốt. Một tài liệu là tất cả mọi người có kiên nhẫn. Một tài liệu "không giải trừ" thứ hai với "các vấn đề khác" dường như không thể đọc được.

Ưu điểm của một tài liệu? Mọi người có thể đọc nó.

Nhược điểm của một tài liệu? Vài. Chủ yếu là nó đã lỗi thời.

Ưu điểm của nhiều tài liệu? Không ai.

Nhược điểm của nhiều tài liệu? Xin vui lòng đọc lên nguyên tắc DRY và lập trình biết chữ. Nhiều tài liệu có nghĩa là nhiều nguồn lỗi. Mỗi tài liệu không đồng ý với nhau và không đồng ý với mã. Điều này là khá rõ ràng. Đây là con đường của sự điên rồ.

Tránh vắt tay.

Một tài liệu ưu và nhược điểm có thể kéo vào những chiều sâu vô định của những cuộc thảo luận phiền toái và hấp dẫn.

Nếu bạn cảm thấy cần phải trình bày những ưu và nhược điểm, hãy giữ nó ngắn gọn và đi vào vấn đề.

Tập trung vào những gì đang có.

Giữ những gì không xuống xương trần.

Nếu bạn đã thực hiện các tiêu chuẩn, nghiên cứu hoặc thực sự khám phá các lựa chọn thay thế, tài liệu đó. Nhưng nếu bạn chỉ đang xem xét các lựa chọn thay thế, hãy giảm thiểu nó.

Đây không phải là lịch sử cá nhân của bạn về thử thách và khổ nạn.

• Đã có vấn đề? Đã sửa chưa? Mất vài tuần? Thực sự vật lộn? Chỉ là một giai thoại thú vị. Nó được cố định trong mã. Các phiên bản trước, phiên bản sai, phiên bản lỗi và phiên bản hiệu suất thấp không thành vấn đề. Họ là tốt nhất cho blog.

• Vẫn có vấn đề? Không cố định? Điều đó có nghĩa là có những lựa chọn thay thế. Tài liệu này.

Có 3 sự thật quan trọng trong quá trình ra quyết định:

• Những gì đã được thử và không hoạt động (và tại sao nó không hoạt động, vì bạn đang nhắm mục tiêu di chuyển)
• Những gì là
• Điều gì có thể xảy ra (chỉ chờ X được thực hiện ...)

Tuy nhiên, ngoài "Cái gì là", tất cả những người khác sẽ khiến người đọc nhầm lẫn và ngăn cô ấy dò dẫm hệ thống.

Tôi thích ý tưởng chụp 2 cái còn lại, mặc dù chúng ít thú vị hơn khi học hệ thống, chúng có thể là những người tiết kiệm thời gian khi thay đổi nó.

Do đó, tôi sẽ xây dựng ý tưởng tiếp xúc @FrustratedWithFormsDesigner, với một bước ngoặt. Thay vì tạo một tài liệu khác, với vòng đời của chính nó, tôi sẽ giải quyết một phần phụ lục. Sau đó, đối với mỗi quyết định xứng đáng để thảo luận, tôi sẽ chỉ ra mục có liên quan trong phụ lục.

Đúng. Một tài liệu thiết kế nên giải thích các lợi ích, rủi ro và các giả định liên quan đến thiết kế được mô tả. Một tài liệu thiết kế có một số mục đích:

1. Nhận thiết kế được viết ra để mọi người hiểu nó và để sự hiểu biết của mỗi người không trôi theo thời gian.

2. Giao tiếp thiết kế cho những người phi kỹ thuật làm việc trong dự án.

3. Hỗ trợ lập kế hoạch, phân bổ nguồn lực, dự toán chi phí và các loại kế hoạch khác.

4. Trở thành một phần quan trọng của tài liệu dự án tổng thể. Khi bạn tham gia vào một dự án đang tiến hành hoặc phải duy trì một dự án đã hoàn thành, cuộc sống sẽ dễ dàng hơn rất nhiều nếu có một tài liệu thiết kế được viết tốt.

5. Thường là một trong những sản phẩm được giao theo yêu cầu của hợp đồng.

(Có lẽ có những người khác, nhưng đây là một khởi đầu tốt.)

Mỗi một trong những mục đích này đều được phục vụ tốt bởi một tài liệu thiết kế giải thích rõ ràng lý do tại sao thiết kế này được chọn và những rủi ro liên quan là gì:

1. Điều cần thiết là mọi người trong nhóm đều biết những rủi ro và lợi ích là gì để họ có thể làm việc cùng nhau để tránh những rủi ro đó và tận dụng tốt nhất các lợi ích của thiết kế.

2. Đối với các thành viên nhóm phi kỹ thuật, việc hiểu các rủi ro và lợi ích thường quan trọng hơn các chi tiết của chính thiết kế.

3. Quản lý rủi ro là một trong những điều quan trọng nhất mà người quản lý dự án có thể làm để đảm bảo thành công và bước đầu tiên là xác định các rủi ro cần được quản lý. Người quản lý phải quyết định cách xử lý rủi ro, nhưng nhà thiết kế có trách nhiệm chỉ ra những rủi ro đã biết của thiết kế.

4. Ngay cả khi rủi ro không còn là vấn đề nữa, việc ghi chép lại nó vẫn hữu ích vì nó có thể giúp giải thích tình huống tại thời điểm thiết kế được tạo ra. Điều đó có thể để một người bảo trì quyết định một cái gì đó như: "Được rồi, họ đã làm theo cách này sau đó bởi vì ... nhưng đó không còn là vấn đề nữa, vì vậy tôi có thể thay thế mã đó bằng cách thực hiện đơn giản hơn, nhanh hơn." Tất nhiên cùng đi cho lợi ích, tất nhiên.

5. Nếu bạn đang làm việc trên một dự án cho một khách hàng, thì điều đặc biệt quan trọng là ghi lại các rủi ro và lợi ích. Điều đó khiến khách hàng chú ý rằng mọi thứ có thể sai trong một số trường hợp hoặc yêu cầu thay đổi thiết kế có thể gây nguy hiểm cho một số lợi ích đã hứa.

Tôi tập hợp từ câu hỏi rằng bạn đang làm việc với một tài liệu thiết kế hiện có cho một hệ thống đã được triển khai. Trong trường hợp đó, nhiều rủi ro có thể không còn là rủi ro nữa, vì vậy sẽ không có ý nghĩa gì khi cố gắng ghi lại chúng sau thực tế. Tuy nhiên, bây giờ bạn có lợi thế về nhận thức muộn vì bạn có thể thấy các phần của thiết kế ban đầu không hoạt động tốt như vậy. Tôi nghĩ bạn nên: thêm một phần riêng biệt xác định các khu vực có vấn đề hiện tại và đề xuất các giải pháp (bao gồm các rủi ro liên quan!); hoặc tạo một tài liệu riêng biệt làm điều tương tự. Phần / tài liệu mới này có thể phát triển thành tài liệu thiết kế cho phiên bản tiếp theo của phần mềm.

Đây là một mục blog về viết tài liệu thiết kế mà bạn có thể thấy hữu ích.

Nếu có những lý do hợp lệ để tránh các giải pháp rõ ràng hơn hoặc tiêu chuẩn, những giải pháp đó cần được lưu ý. Bạn sẽ cứu ai đó rất nhiều rắc rối. Tuy nhiên, một công nghệ cụ thể có thể cải thiện theo thời gian, vì vậy lý do của bạn có thể không được áp dụng. Một nhà phát triển trong tương lai sau đó có thể sử dụng phán đoán của riêng họ.

Tôi không biết nếu có nhiều lợi ích để chỉ ra tất cả các truyện ngắn. Nó có thể không thực tế để thực hiện các thay đổi hoặc các ưu tiên khác sẽ diễn ra. Bạn có thể sửa một số trong số chúng trong tương lai gần và đây sẽ chỉ là một điều nữa để cập nhật.

Cá nhân tôi sẽ không đưa nó vào tài liệu thiết kế. Một tài liệu thiết kế nên phác thảo nó như thế nào, không phải tại sao nó là.

Nếu bạn cảm thấy cần có một câu chuyện ngược lại về lý do tại sao thiết kế lại như vậy, có lẽ bạn nên đặt nó trong một bài viết wiki (hoặc bất kỳ cơ sở kiến ​​thức nào mà công ty bạn sử dụng) để có thể có một lịch sử về sự phát triển của thiết kế. Mọi người có thể đi và đọc nó, chỉnh sửa nó và thêm đề xuất. Theo cách đó, nó giống như một cuộc thảo luận mở hơn là một cú đánh trong tài liệu.

Tôi đồng ý với bạn về việc đưa lý do vào tài liệu thiết kế.

Dù sao,

trong quá trình cập nhật một tài liệu thiết kế được viết bởi người khác, tôi sẽ khiêm tốn và không cố đoán tại sao quyết định đó lại được đưa ra.

Vì thế,

Tôi sẽ chỉ chèn lý do về những thay đổi được thực hiện trong thiết kế trong quá trình bảo trì.