Tạo một trang web và tài liệu thư viện C ++ hiệu quả

Tạo thư viện C ++ cũng có nghĩa là ghi lại nó để người khác có thể sử dụng nó và tài liệu đó có thể thay đổi đáng kể về chất lượng.

Làm thế nào một trang web cho một thư viện C ++ được cấu trúc để nó có hiệu quả nhất?

Tôi sẽ đóng khung "hiệu quả nhất" khi được chia thành ba nhóm các bên liên quan đến thư viện cụ thể, mỗi nhóm có thể tìm và tìm hiểu những gì họ cần tham gia và sử dụng thư viện:

1. Người dùng mới cần một phần giới thiệu, tải xuống, thiết lập và tài liệu tuyệt vời, rõ ràng chuyển từ bước này sang bước tiếp theo.

2. Người dùng dày dạn cần một tài liệu tham khảo vững chắc với quyền truy cập nhanh vào các chi tiết họ cần và thông tin rõ ràng về các bản cập nhật mới.

3. Những người đóng góp mới cần một cách hướng dẫn bao gồm các bước họ phải thực hiện để có được những đóng góp của họ vào thư viện.

Tôi muốn tìm ra cách làm cho mỗi người rất hài lòng với những gì họ thấy và sử dụng. Câu hỏi này là một chút giao thoa giữa lập trình chuyên nghiệp và trải nghiệm người dùng.

Đối với các ví dụ cụ thể, Boost là một trong những bộ sưu tập thư viện tốt nhất, nhưng cài đặt ban đầu, tài liệu tham khảo và tìm ra cách đóng góp có thể hơi khó hiểu.

Mặt khác, tôi đã tìm thấy cppreference.com và tài liệu SGI STL rất rõ ràng và hữu ích với các giải thích, liên kết và ví dụ.

Mặc dù các ví dụ chỉ là ý kiến ​​và những người khác có thể khác nhau, nhưng nó giúp đưa ra bối cảnh cho câu hỏi tôi đang hỏi.

Trong công ty trước đây của chúng tôi, chúng tôi đã bắt đầu tạo tài liệu và có một công việc CI hoạt động hàng đêm và đăng nó dưới dạng một tập hợp các trang web mà wiki của nhóm chúng tôi sau đó sẽ đề cập đến.

Như đã đề xuất trong các bình luận cho câu hỏi của bạn, chúng tôi đã sử dụng doxygen. Một điều tôi thực sự thích được giới thiệu trong phiên bản 1.8 là khả năng có một thư mục (hoặc toàn bộ cây) các tài liệu đánh dấu trong khi trước đó doxygen được tạo hoàn toàn từ các tệp nguồn.

Cấu trúc chúng tôi có là một màn hình chào mừng (đánh dấu) có liên kết đến nhiều nơi khác nhau. Một trong số đó là kiến ​​trúc sản phẩm cho thấy tầm nhìn 30.000 feet của sản phẩm và làm nổi bật các dịch vụ chính. Sau đó, từ trang đó, đã có lượt thích các trang đánh dấu khác mở rộng từng dịch vụ và trình bày thiết kế ở mức rất cao của mỗi dịch vụ (chế độ xem 10k?).

Cũng từ trang chính, chúng tôi đã có các liên kết đến các bộ sưu tập hướng dẫn sử dụng mà chúng tôi đã viết để giải thích cách sử dụng một số mã tiện ích / khung công tác phổ biến.

Và chúng tôi dần dần bắt đầu chuyển các tài liệu thiết kế hiện có (được viết bằng MS Word và được lưu trữ trong điểm chia sẻ) sang định dạng doxygen thực sự dễ dàng hơn mọi người mong đợi. Nếu không phải là sơ đồ, phải được xuất riêng lẻ và được lưu dưới dạng JPEG, tài liệu thiết kế 20-30 trang có thể được chuyển đổi thành định dạng đánh dấu doxygen trong khoảng 15-30 phút và thật đơn giản, một co-op có thể làm điều đó ^{( *)} .

Cái hay mà tôi yêu thích khi sử dụng doxygen cho loại tài liệu này bên cạnh việc nó có thể tạo HTML hoặc PDF từ cùng một nguồn, là chúng tôi có thể liên kết tất cả tài liệu của mình trực tiếp với các trang tham chiếu lớp / chức năng được tạo bằng cách phân tích tệp tiêu đề. Vì vậy, nó là một cấu trúc rất đẹp sẽ đi từ "welcome" -> "architecture" -> "design" -> ngay xuống tài liệu cấp lớp.

Và vì toàn bộ vấn đề đã được đánh dấu, việc tạo nội dung rất đơn giản (dễ dàng hơn nhiều so với cố gắng giải thích cho nhóm kỹ sư về cách sử dụng chính xác MS Word Styles) và tài liệu đã được kiểm tra ngay tại đó bằng mã nguồn, vì vậy các phiên bản mới đã được giới thiệu và thiết kế / kiến ​​trúc được sửa đổi, tài liệu sẽ luôn được đồng bộ hóa với nó.

---

^(*) - j / k chúng tôi đã có những hợp tác tuyệt vời (phần lớn) và họ đã có nhiều đóng góp tuyệt vời cho sản phẩm, nhưng tôi đã thực hiện một trong số họ thực hiện một số chuyển đổi tài liệu.