Creating a C++ library also means documenting it so that others can use it, and that documentation can vary dramatically in quality.
How should a website for a C++ library be structured so that it is most effective?
I would frame “most effective” as being divided among three specific groups of library stakeholders, which should each be able to find and learn what they need to participate in and use the library:
-
New users need an excellent, easy introduction, download, setup, and documentation that clearly flows from one step to the next.
-
Seasoned users need a solid reference with fast access to the details they need, and clear information about new updates.
-
New contributors need a how to guide covering the steps they must take to get their contributions into the library.
I would like to figure out how to make each very happy with what they see and use. This question is a bit of a cross between professional programming and user experience.
For specific examples, Boost is one of the best collections of libraries, but the initial installation, reference documentation, and figuring out how to contribute can be somewhat confusing.
On the other hand, I have found cppreference.com and the SGI STL documentation to be very clear and useful with explanations, links, and examples.
While the examples are merely opinions and others may differ, it does help give context to the question I am asking.
4
In my previous company we started generating documentation and having a CI job run nightly and post it as a set of webpages which our team’s wiki would then refer to.
As was suggested in comments to your question, we used doxygen. One thing I really liked that was introduced in version 1.8 was ability to have a directory (or whole tree) of markdown documents whereas before that doxygen was generated purely from source files.
The structure we had was a welcome screen (markdown) which had links to various places. One of them was a product architecture which showed 30,000 foot view of the product and highlighted major services. Then from that page, there were likes to other markdown pages that expanded each of the services and presented very high level design of each one (10k foot view?).
Also from the main page, we had links to collections of user guides that we wrote to explain how to use some common utility/framework code.
And we slowly started migrating existing design documents (written in MS Word and stored in share point) into doxygen format which actually proved easier than one would expect. If not for the diagrams, which had to be exported individually and saved as JPEGs, a 20-30 page design document could be converted into doxygen markup format in about 15-30 minutes and it was so simple a co-op could do it (*).
The beauty which I loved about using doxygen for this type of documentation besides that it could generate HTML or PDF from the same source, was that we could tie all our documentation directly to class/function reference pages that were generated by parsing header files. So it was a very nice structure that would go from “welcome” -> “architecture” -> “design” -> right down to class-level documentation.
And as the whole thing was in markdown, it was very simple to generate content (much easier than attempting to explain to a team of engineers how to correctly use MS Word Styles) and documentation was checked in right there with the source code, so as new versions were introduced and design/architecture modified, documentation would always stay synced up with it.
(*) – j/k we had great co-ops (for the most part) and they made many awesome contributions to the product, but I did make one of them do some of the doc conversion.