Tôi được giao nhiệm vụ lãnh đạo nỗ lực tài liệu cho một sản phẩm phần mềm hiện có, hoàn toàn không có giấy tờ - có những nguồn lực nào để giúp tôi?


9

Tôi là một nhà phát triển phần mềm tại một công ty công nghệ. Tôi đã được giao nhiệm vụ lãnh đạo nỗ lực tài liệu cho sản phẩm tôi làm việc. Mục tiêu là sản xuất tài liệu nội bộ cho nhà phát triển và dự án tràn sang phía doanh nghiệp, nơi nó bao gồm các tài liệu yêu cầu.

Dự án này là một thách thức. Cụ thể, tôi đang giao dịch với một sản phẩm: - đã xuất hiện từ lâu, ít nhất là 6 năm. - không có hình thức tài liệu nào khác ngoài một số phần nhỏ, lỗi thời ở đây và đó. - có ý kiến ​​trong mã, nhưng chúng là kỹ thuật và không truyền đạt bất kỳ hành vi quá cong nào (ngay cả về mặt kỹ thuật). - do hậu quả của việc có ít hoặc không có tài liệu, thường phức tạp không cần thiết dưới vỏ bọc

Ngoài ra, chúng tôi đã không được dành nhiều thời gian để làm việc trong dự án này.

Tôi không có bất kỳ tài liệu chính thức hoặc nền tảng viết, đào tạo hoặc kinh nghiệm. Tôi đã thể hiện một số khả năng bằng văn bản / giao tiếp xung quanh văn phòng, đó có thể là lý do tại sao tôi được giao cho dự án này.

Vui lòng chia sẻ lời khuyên hoặc đề xuất của bạn cho các tài nguyên để giúp tôi chuẩn bị và đối phó với dự án này. Tôi đang tìm tài liệu tham khảo cho sách / trang web / diễn đàn / bất cứ điều gì, để giúp tôi đưa ra thiết kế kế hoạch với các mốc quan trọng, tìm hiểu về thực tiễn tốt nhất, phân công nhiệm vụ, mẫu, mua, v.v.

Tôi hy vọng đặc biệt cho các tài nguyên nhắm mục tiêu hoặc đưa ra đề cập đặc biệt về việc giới thiệu tài liệu tốt cho các dự án hiện có, không có giấy tờ .


1
Dự án được viết trong là gì? Có các công cụ cho nhiều ngôn ngữ để trích xuất thông tin từ các tiêu đề chức năng và những thứ khác. Bạn sẽ không nhận được bất cứ điều gì hữu ích trực tiếp từ họ, nhưng họ có thể giúp đỡ.
David Thornley

Âm thanh như công việc tôi sử dụng để làm việc. khoảng 6 năm mã Delphi 7 và khoảng 200 SQL Server được lưu trữ procs / hàm / trình kích hoạt được kết hợp với nhau mà không có tài liệu.
Earlz

Câu trả lời:


8

Tôi thường sử dụng wiki và chỉ những thứ spam ở đó khi tôi trải qua quá trình khám phá. Wiki vì bạn có được tìm kiếm và lịch sử cũng như các chức năng chỉnh sửa nhóm. Công cụ chính xác ít quan trọng hơn việc tìm kiếm chức năng và giúp mọi người sử dụng nó. Ban đầu, dự kiến ​​nó sẽ rất thô, nhưng khuyến khích mọi người tạo ra những ghi chú thô khi họ đi vì đó là tất cả những gì bạn sẽ nhận được lúc đầu.

Một vài điều giúp ích rất nhiều:

  • có một biên tập viên. Bạn, có lẽ, lúc đầu, nhưng nếu bạn có ngân sách, hãy biến nó thành một phần công việc của ai đó. Chọn một người giỏi ngôn ngữ hơn là một chuyên gia kỹ thuật. Chỉnh sửa cho rõ ràng hơn là hoàn hảo - bạn muốn khuyến khích mọi người viết các mục tốt nhưng trước tiên bạn sẽ cần hướng dẫn họ.
  • sử dụng sơ đồ, nhưng bắt buộc phải sử dụng một công cụ có liên quan, hình ảnh được tạo và tệp nguồn được đính kèm vào trang. Bằng cách đó, mọi người có thể chỉnh sửa hình ảnh của bạn bằng công cụ thích hợp thay vì MS-Paint. Rất ít thứ hấp dẫn hơn một sơ đồ thực sự tốt được xây dựng trong Visio mà bạn không có tài liệu nguồn nào nữa, chỉ có một PNG được trích xuất từ ​​nó.
  • Khuyến khích sắp xếp lại và chỉnh sửa. Ngay cả khi nó không tuyệt vời lúc đầu, bạn cần mọi người đối chiếu thông tin và sửa lỗi. Người cố vấn để làm tốt điều này.
  • mang điều này lên trong các cuộc họp nhóm hàng tuần của bạn. Lấy danh sách các chỉnh sửa gần đây trước khi bạn đi vào và khen ngợi những người đã thêm bất cứ điều gì hữu ích, sau đó hỏi tại sao những người không, không có.

Tôi đã bắt đầu với một hình ảnh máy ảo MediaWiki trong quá khứ bởi vì nó rất nhanh và dễ dàng để bắt đầu, vì vậy mọi người nói rằng "nó quá khó" không có bất kỳ lực kéo ban đầu nào.

Nếu ngôn ngữ / môi trường của bạn hỗ trợ nó bằng cách sử dụng các công cụ loại JavaDoc / NDoc để trích xuất các nhận xét khi bạn thêm chúng là một cách tiếp cận cấp thấp tốt. Nhưng điều đó ít hữu ích hơn tài liệu cấp cao và mặc dù các loại công cụ hỗ trợ thêm công cụ cấp cao hơn, việc tạo ra nó từ không có gì chỉ sử dụng những công cụ đó là không cần thiết.


2
+1: Wikis là một công cụ tuyệt vời cho việc này. Tôi đã sử dụng phương pháp này nhiều lần trong sáu năm qua để ghi lại mã không có giấy tờ theo cách tiến hóa - và chúng rất dễ dàng, bạn cũng có thể đưa một số đồng nghiệp của mình lên tàu.
Bob Murphy

Điều tốt nhất về wiki là bạn có thể dễ dàng nhận được đầu vào trực tiếp từ những người sử dụng và phát triển phần mềm.
HorusKol

3
Và trả lời câu trả lời với "tuyệt vời, nhưng tại sao không có trong wiki?". Nếu nhóm của bạn không quen với việc có tài liệu, ban đầu sẽ có một chút sốc. Toàn bộ "tìm nhà phát triển duy trì điều này và hỏi họ" gây khó chịu cho mọi người, nhưng cần có thời gian để mọi người quen với việc trả nó về phía trước.

Wikis cũng có xu hướng gây nghiện. Khi bạn đã chọn một thông tin có đủ thông tin và khiến một số người có thói quen cập nhật và kiểm tra nó, wiki có thể biến thành một nguồn tài liệu dài hạn cho dự án.
quả việt quất

4

Nếu bạn đang tự viết tài liệu mã và không thực hiện tài liệu người dùng cuối, Doxygen là một công cụ tuyệt vời nếu ngôn ngữ phát triển của bạn được hỗ trợ. Bạn chạy mã trên mã của mình và nó tạo ra một trang web liệt kê tất cả các chức năng, lớp, v.v. Sau đó, bạn có thể thêm nhận xét mã được định dạng đặc biệt để nhóm các thứ và thêm chi tiết. Đó là một cách tuyệt vời để tăng dần tài liệu cơ sở mã.


1
+1 cho Doxygen. Hãy chắc chắn rằng bạn cho phép tạo sơ đồ lớp và biểu đồ cuộc gọi. Đây là vô giá khi điều hướng qua một biển mã không có giấy tờ.
GavinH

@GavinH, có một chút khó hiểu khi bạn đã thêm một bình luận "+1" nhưng không có sự phản hồi thực sự về câu trả lời này.
Péter Török

Wow, các bạn đừng bỏ lỡ một nhịp!
GavinH

2

Liên quan đến việc ghi lại mã tự nó, nếu Doxygen không phù hợp với nhu cầu của bạn, có rất nhiều công cụ thay thế có sẵn. Wikipedia có một danh sách gần 50 công cụ như vậy và bao gồm các chi tiết về chức năng và hỗ trợ ngôn ngữ của chúng.

Tuyên bố miễn trừ trách nhiệm: Tôi được liên kết với một trong những công cụ, Imagix 4D .


1

Đây chỉ là một vài ý tưởng có thể hữu ích ở một mức độ nào đó:

Bạn có nghĩ cuối cùng tài liệu này sẽ lấy mẫu nào không nó, sử dụng một số hệ thống quản lý tài liệu sẵn có như Share Point, hay cái gì khác? Lấy kết quả sẽ là một ví dụ về một cuốn sách trực tuyến là một loạt các trang chẳng hạn.

Loại quy trình kiểm soát và chỉnh sửa nào mà bạn muốn tài liệu này thực hiện là một vấn đề khác có thể đáng suy ngẫm trước khi bạn đi quá xa vào vấn đề này. Làm thế nào để bạn muốn xử lý cập nhật và thay đổi.

Phản hồi có thể là một khía cạnh thú vị khác về vấn đề này vì bất cứ điều gì bạn tạo ra đều có thể sẽ có nhiều hơn một vài lời phê bình và những thay đổi đó được ưu tiên và tiết kiệm như thế nào là một câu hỏi khác mà tôi xem xét trước khi đưa ra phiên bản đầu tiên đó.

Chúc may mắn!


1

Xây dựng Tài liệu, giống như xây dựng tất cả các loại phần mềm khác, là một quy trình phức tạp vốn có.

Đó là lý do tại sao các nhà phát triển phần mềm đã phát minh ra các phương thức Agile.

Tài liệu chỉ là phần mềm không có trình biên dịch. Các phương pháp tương tự cho các dự án phần mềm áp dụng cho các dự án tài liệu. Chính xác là cùng lý luận.

Khi bạn viết phần mềm, bạn bắt đầu với các trường hợp sử dụng (hoặc câu chuyện của người dùng). Tài liệu cũng không khác.

Bạn ưu tiên các trường hợp sử dụng với ngân sách gần đúng.

Bạn có nước rút.

Bạn có bản phát hành.

Bạn đảm bảo chất lượng - kiểm tra - xem xét - chỉnh sửa và phát hành lại.

chính xác như xây dựng phần mềm.

Người dùng của bạn là ai? Họ có vấn đề gì? Tài liệu sẽ giải quyết vấn đề của họ như thế nào? Ưu tiên. Tăng tốc. Cuối cùng, bạn sẽ phát hành.

Khi sử dụng trang web của chúng tôi, bạn xác nhận rằng bạn đã đọc và hiểu Chính sách cookieChính sách bảo mật của chúng tôi.
Licensed under cc by-sa 3.0 with attribution required.