Đặt tài liệu mã ở đâu?

Tôi hiện đang sử dụng hai hệ thống để viết tài liệu mã (đang sử dụng C ++):

• Tài liệu về các phương thức và các thành viên lớp được thêm vào bên cạnh mã, sử dụng định dạng Doxygen. Trên máy chủ, Doxygen được chạy trên các nguồn để có thể nhìn thấy đầu ra trong trình duyệt web
• Các trang tổng quan (mô tả một tập hợp các lớp, cấu trúc của ứng dụng, mã ví dụ, ...) được thêm vào Wiki

Cá nhân tôi nghĩ rằng cách tiếp cận này dễ dàng vì tài liệu về các thành viên và các lớp thực sự gần với mã, trong khi các trang tổng quan thực sự dễ chỉnh sửa trong Wiki (và cũng dễ dàng để thêm hình ảnh, bảng, ...). Một trình duyệt web cho phép bạn xem cả hai tài liệu.

Đồng nghiệp của tôi bây giờ đề nghị đưa mọi thứ vào Doxygen, vì sau đó chúng tôi có thể tạo một tệp trợ giúp lớn với mọi thứ trong đó (sử dụng HTML WorkShop của Microsoft hoặc Qt Assistant). Mối quan tâm của tôi là việc chỉnh sửa tài liệu theo kiểu Doxygen khó hơn nhiều (so với Wiki), đặc biệt là khi bạn muốn thêm bảng, hình ảnh, ... (hoặc có một công cụ 'xem trước' cho Doxygen không yêu cầu bạn tạo mã trước khi bạn có thể thấy kết quả?)

Các dự án nguồn mở lớn (hoặc nguồn đóng) sử dụng để viết tài liệu mã của họ là gì? Có phải họ cũng phân chia điều này giữa phong cách Doxygen và Wiki? Hay họ sử dụng một hệ thống khác?

Cách thích hợp nhất để lộ tài liệu là gì? Thông qua máy chủ / trình duyệt Web hoặc qua tệp trợ giúp lớn (vài 100 MB)?

Cách tiếp cận nào bạn thực hiện khi viết tài liệu mã?

Có tất cả tài liệu trong một hệ thống thay vì hai có thể là một lợi thế thực sự. Những thứ như sao lưu và khôi phục, tạo phiên bản, tìm kiếm toàn cầu, tìm kiếm và thay thế toàn cầu, liên kết chéo và, như bạn đã viết, đặt tất cả các tài liệu vào một tài liệu cuối cùng, thường sẽ hoạt động với ít "ma sát" hơn khi bạn không phải duy trì hai cách khác nhau các hệ thống với capoverites chồng chéo.

Mặt khác, bạn phải suy nghĩ xem liệu những lợi thế này có vượt trội hơn mức độ dễ dàng của Wiki của bạn hay không. Vòng tròn chỉnh sửa / tạo / tinh chỉnh chỉnh sửa / tạo lại có thể nhanh hơn với Wiki của bạn. Tôi đoán rằng bạn có thể có được chu trình đó khá nhanh với doxygen giữ các trang tổng quan của bạn dưới dạng một tiểu dự án doxygen riêng biệt. Dĩ nhiên, bạn có thể sử dụng các khả năng liên kết bên ngoài của doxygen, đây không phải là sự thay thế cho "bản xem trước nhanh", mà là một bước theo hướng đó. Tôi đã không làm điều này một mình, cho đến nay, nhưng tôi đoán bạn phải tự mình thử nó nếu bạn muốn biết nếu nó hoạt động trong trường hợp của bạn.

Liên quan đến các dự án khác: Tôi nghĩ rằng một công cụ như doxygen chủ yếu dành cho tài liệu thư viện. Nếu bạn không phải là nhà cung cấp thư viện của bên thứ ba và mọi người sử dụng thư viện của bạn đều có quyền truy cập đầy đủ vào mã nguồn, thì cần phải có một công cụ như doxygen. Ví dụ, trong nhóm của chúng tôi, chúng tôi hầu như không có tài liệu bên ngoài mã nào ngoại trừ tài liệu người dùng cuối và tài liệu của các mô hình cơ sở dữ liệu của chúng tôi. Các công cụ chính của chúng tôi cho loại tài liệu đó là docbook và fop , mang lại cho chúng tôi kết quả hài lòng.

Sử dụng Tài liệu Mã, đầu tiên. Thêm Wiki và các phương pháp khác, nếu có thể

Tôi biết, điều đó sẽ khó khăn, để duy trì nó.

Câu trả lời thực tế:

Trong điều kiện thực tế, điều đầu tiên mà các nhà phát triển làm, đó là kiểm tra mã.

Là một nhà phát triển, tôi muốn có tài liệu bên ngoài, như Wiki (s), hướng dẫn sử dụng. Nhưng, điều đầu tiên tôi làm, đó là xem xét mã (đôi khi từ các nhà phát triển khác, đôi khi, của riêng tôi).

Là một nhà phát triển, làm việc trong một số dự án và khách hàng, tôi làm hết sức có thể để thêm tài liệu bên ngoài, nhưng, thông thường có rất nhiều khối lượng công việc và không thể hỗ trợ wiki.

Đôi khi, người quản lý dự án và các ông chủ khác không quan tâm đến tài liệu, đôi khi các nhà phát triển khác không làm như vậy.

Và, điều tốt nhất tôi có thể làm, đó là thêm một số bình luận vào mã.

Chúc may mắn

Một số sử dụng các hệ thống khác - ví dụ, hãy xem Sphinx của Python , họ có một hệ thống tài liệu tất cả trong một, xây dựng mọi thứ (nó cũng hoạt động cho C / C ++)

Tôi luôn nghĩ tài liệu là riêng biệt với mã, doxygen là tuyệt vời, nhưng nó là để có cái nhìn tổng quan về API, không phải là "tài liệu". Vì thế, wiki rất tuyệt, nhưng tôi thích sử dụng ASCIIDOC và lưu trữ kết quả của điều khiển nguồn đó cùng với mã, chủ yếu vì tôi có thể tạo tệp PDF từ nó để trao cho người khác (ví dụ: người kiểm tra, khách hàng, v.v.)

Doxygen cho phép bạn xây dựng các trang PDF, HTML, wiki, hầu hết mọi thứ bạn có thể nghĩ ra.

Sở thích cá nhân của tôi là có cả Doxygen và wiki và một kịch bản hoặc thứ gì đó để kiểm tra khi chúng phân kỳ.

Do phiên bản 1.8.0 doxygen hỗ trợ Markdown , điều này sẽ giúp trải nghiệm viết các trang tĩnh trở nên thuận tiện tương tự như trong hệ thống Wiki.

Khán giả mục tiêu

Tôi nghĩ khi trả lời câu hỏi này, bạn thực sự cần phải hỏi ai là người đọc tài liệu này. Nhà phát triển có nhu cầu rất khác nhau đối với Người dùng hoặc thậm chí là Chuyên viên phân tích nghiệp vụ.

• Là nhà phát triển: tài liệu liên quan đến mã đang được nghiên cứu, các chi tiết như hợp đồng giao diện và ví dụ về cách sử dụng. Có lẽ một số tài liệu cấp cao, và thông số kỹ thuật giao thức cho biện pháp tốt.
• Là người dùng: tài liệu có sẵn thông qua menu trợ giúp hoặc trang web có thể truy cập về cách sử dụng phần mềm.
• Là một Nhà phân tích kinh doanh: tài liệu có sẵn dưới dạng tài liệu hoặc như một trang web có thể truy cập đều hữu ích. Một lượng chi tiết khiêm tốn về các giao thức, kiến ​​trúc cấp cao và các trường hợp sử dụng là tốt nhất.

Bảo trì

Nơi đặt nguồn cho tài liệu này sẽ phụ thuộc vào đối tượng của bạn và ai đang viết cho khán giả của bạn.

• Chỉ có một ngôi nhà của các nhà phát triển? Đặt mọi thứ trong mã. Nó sẽ khuyến khích nó được cập nhật. Bạn sẽ cần phải làm việc trên một nền văn hóa khuyến khích các cập nhật tài liệu cũng quan trọng như thay đổi mã.
• Có một ngôi nhà của các nhà phát triển và nhà văn tài liệu? Phân chia trách nhiệm. Sử dụng công cụ định hướng dành cho nhà phát triển cho nhà phát triển, sử dụng công cụ viết tài liệu cho người viết tài liệu.

Trường hợp có thể đảm bảo rằng các ví dụ mã hoặc trường hợp sử dụng có thể được thực thi. Tự động thực hiện của họ và thất bại cờ nội bộ. Có thể những trang này là tài liệu kém hoặc xấu.

Ngoài ra, bất kỳ công cụ nào bạn chọn để viết tài liệu của mình vào, bạn cần một phương tiện đáng tin cậy để liên kết một phiên bản cụ thể của tài liệu với một phiên bản mã cụ thể. Điều này vẫn có lợi ngay cả ở vùng đất đám mây hạnh phúc với một triển khai thường xanh duy nhất.

Tài liệu tích hợp

Tích hợp có thể cần thiết để tạo ra một số tài liệu, nhưng lưu ý rằng chỉ người dùng mới mong đợi một nơi duy nhất để truy cập tất cả các tài liệu họ cần.

Nhà phân tích kinh doanh khá hài lòng với thông số API, Thông số thiết kế và kịch bản sử dụng được đặt trong các tài liệu riêng biệt hoặc các phần riêng biệt của trang web.

Nhà phát triển thích mọi thứ có thể nhìn thấy từ nguồn, nhưng khá vui khi có một vài tài liệu thiết kế cấp cao và các tài liệu đặc tả giao thức chi tiết bên ngoài mã, mặc dù tốt nhất là trong cùng một kiểm tra.

Trường hợp của bạn

Thành thật mà nói, tài liệu trong wiki của bạn có thể không giống với loại tài liệu trong cơ sở mã của bạn. Nó có thể không có ý nghĩa để hợp nhất quá.

Mặt khác, việc tích hợp cả hai có thể được cung cấp theo một vài cách đơn giản.

• Các công cụ tài liệu nguồn (như doxygen) có thể tạo html và wiki sống trên máy chủ web. Nó sẽ là một điểm tích hợp đơn giản để chỉ phục vụ một phiên bản được xây dựng cùng với wiki và liên kết cả hai.
• Một số sản phẩm wiki sẽ cho phép bạn chạy wiki trực tiếp từ một tệp mà bạn có thể đăng ký vào cơ sở mã. Điều này cung cấp một công cụ wysiwyg đơn giản trong khi giữ cho tài liệu được ghép nối với mã.
• Các định dạng khác như pdf cũng có thể được cung cấp, nhưng điều này sẽ đi vào công cụ cụ thể mà bạn muốn sử dụng. Có thể có ý nghĩa để cạo wiki của bạn thành các tệp markdown và cung cấp thông qua doxygen (hoặc các công cụ khác). Nó có thể có ý nghĩa với pdf wiki và nguồn riêng biệt và sử dụng một công cụ hợp nhất pdf.

Vào cuối ngày, hãy tìm ra hệ thống tài liệu nào có chi phí bảo trì thấp và hỗ trợ bạn cung cấp một sản phẩm chất lượng cao mà khán giả của Nhà phát triển, Nhà phân tích kinh doanh và Người dùng của bạn nhìn thấy. Bất cứ điều gì cản trở bất kỳ nhóm nào trong số này sẽ nhất thiết làm giảm chất lượng sản phẩm.

Nếu bạn đang sử dụng ASCII, bạn nên lưu trữ dữ liệu tài liệu của mình trong phần mã nguồn cao! Sau đó, chỉ những người dùng thông minh nhất (đọc: xứng đáng) mới có cơ hội sử dụng tài liệu của bạn.

Có tài liệu ở định dạng di động được xác định rõ, dễ xuất khẩu, có thể là lợi thế thực sự. Nếu nhân sư chết (không chắc) tôi sẽ chuyển đổi sang hệ thống khác, mà tôi đoán sẽ là một nhiệm vụ có thể viết được. Di chuyển dữ liệu ra khỏi wiki (có lẽ được lưu trữ trong cơ sở dữ liệu ở định dạng độc quyền có thể là một nỗi đau).