Làm cách nào để quản lý tài liệu của dự án nguồn mở? [đóng cửa]

Tôi là người tạo ra một dự án nguồn mở đang phát triển. Hiện tại, tôi đang trở nên bối rối khi cố gắng tìm ra cách tốt nhất để quản lý tài liệu. Dưới đây là các tùy chọn tôi đã xem xét:

• Trang web HTML
• Wiki Github
• Tập tin Markdown được lưu trữ trên Github
• Đặt tất cả tài liệu trong Github README.md

Tài liệu đã được viết bằng Markdown, tôi chỉ không thể hiểu làm thế nào tôi muốn làm cho nó có sẵn. Tôi thực sự bị cuốn hút bởi Git vì tôi có thể phân nhánh và gắn thẻ tài liệu giống như tôi có thể phân nhánh và gắn thẻ nguồn.

Tôi có thể sử dụng thư viện Markdown để dịch Markdown sang HTML và hiển thị nó trên một trang web theo kiểu. Tôi sẽ cần phải tải lên các thay đổi lên trang web bất cứ khi nào có thay đổi và rất khó để quản lý tất cả các "thẻ" khác nhau của tài liệu.

Github Wikis (theo như tôi biết) không thay đổi theo chi nhánh bạn đang ở. Vì vậy, tôi chỉ có thể có phiên bản "chính" của tài liệu ở dạng Github Wiki tại bất kỳ thời điểm nào.

Đặt tất cả vào Github README là khá gọn gàng. Tôi nhận được phân nhánh và gắn thẻ, nhưng nó hơi mệt khi sử dụng và không cho vay tốt để điều hướng dễ dàng.

Tôi có thiếu một số giải pháp tuyệt vời? Tôi có những lựa chọn nào khác?

Một điều tôi muốn nói là tài liệu PHẢI có trong các tệp mã nguồn (sử dụng bất kỳ đánh dấu nào bạn muốn) và sau đó các tài liệu được tạo tự động từ các tài liệu này.
Ít nhất trên trang web của bạn, bạn có thể tạo các bản tải xuống được định dạng của các tài liệu như một phần của gói nguồn để người dùng không cần một công cụ tài liệu cụ thể

Cơ hội để người khác sửa / thêm chức năng và sau đó chỉnh sửa / thêm một chút tài liệu đánh dấu ngay lập tức trong cùng một tệp có thể thấp NHƯNG khả năng họ tìm thấy một tệp hoàn toàn khác trong kho lưu trữ tài liệu khác để thực hiện tương tự nhỏ hơn không.

Bạn luôn có thể có một hướng dẫn.h có chứa các khối văn bản lớn nếu bạn muốn - nhưng coi nó như một phần của nguồn

Nếu dự án của bạn là một thư viện, không có gì vượt qua tài liệu kiểu javadoc để ghi lại cú pháp API từ các nhận xét trong chính mã.

Đối với các tài liệu về hướng dẫn, ví dụ sử dụng, vv Tôi rất khuyên bạn nên sử dụng định dạng wiki. Các dự án khác tôi đã thấy có các trang riêng cho các chi nhánh khác nhau. Khi bạn bắt đầu một chi nhánh mới, bạn chỉ cần sao chép những thứ chưa thay đổi sang một trang mới và cập nhật từ đó.

Lý do của tôi để giới thiệu wiki là giai thoại, nhưng từ kinh nghiệm cá nhân. Tôi đã đóng góp các bản cập nhật tài liệu cho các dự án nguồn mở trong một số trường hợp, nhưng tất cả chúng đều có trên wiki. Nếu tôi đang cố gắng tìm ra một cái gì đó và tài liệu bị sai lệch hoặc không có ích, sau khi tôi nhận ra tôi sẽ cập nhật wiki trong khi tôi đang ở trong tài liệu và nó mới mẻ trong tâm trí tôi. Nếu không phải là không có ý nghĩa trả lại, thì ít nhất bởi vì tôi biết tôi có khả năng cần phải tự mình tìm kiếm lại sau một hoặc hai năm nữa.

Nếu không có wiki, thì rào cản gia nhập quá cao để làm phiền, giữa việc tìm ra cách tạo tài liệu, nơi lưu trữ, nhận bản mới nhất từ ​​kiểm soát nguồn, cách chỉnh sửa, chỉnh sửa thực tế và điều hướng các danh sách gửi thư để có được một bản vá được chấp nhận.

Nếu bạn muốn kiểm soát chặt chẽ tài liệu của mình, bằng mọi cách, hãy sử dụng bất cứ điều gì thoải mái nhất cho bạn, bởi vì bạn hầu như sẽ là người duy nhất cập nhật nó. Nếu bạn muốn khuyến khích sự tham gia của cộng đồng, hãy sử dụng wiki.

Markdown Files Được lưu trữ với nguồn hoạt động rất tốt.

Ví dụ, các công cụ docutils dựa trên RST có thể tạo HTML hoặc LaTex (và PDF) từ một bộ tài liệu.

Điều này - có hiệu lực - kết hợp tùy chọn 1 của bạn và tùy chọn 3.

Nếu bạn không ngại chuyển đổi các tài liệu từ Markdown sang tái cấu trúc, hãy xem xét Nhân sư . Nó dễ như đánh dấu, nhưng nó mạnh hơn rất nhiều.