I am currently using two systems to write code documentation (am using C++):
- Documentation about methods and class members are added next to the code, using the Doxygen format. On a server Doxygen is run on the sources so the output can be seen in a web browser
- Overview pages (describing a set of classes, the structure of the application, example code, …) is added to a Wiki
I personally think that this approach is easy because the documentation about members and classes is really close to the code, while the overview pages are really easy to edit in the Wiki (and it's also easy to add images, tables, …). A web browser allows you to see both documentations.
My co-worker now suggests to put everything in Doxygen, because we can then create one big help file with everything in it (using either Microsoft's HTML WorkShop or Qt Assistant). My concern is that editing Doxygen-style documentation is much harder (compared to Wiki), especially when you want to add tables, images, … (or is there a 'preview' tool for Doxygen that doesn't require you to generate the code before you can see the result?)
What do big open-source (or closed source) projects use to write their code documentation? Do they also split this up between Doxygen-style and a Wiki? Or do they use another system?
What is the most appropriate way to expose the documentation? Via a Web server/browser, or via a big (several 100MB) help file?
Which approach do you take when writing code documentation?
Best Answer
Having all documentation in one system instead of two can be a real advantage. Things like backup & restore, versioning, global search, global search&replace, cross-linking, and, as you wrote, putting all docs in one final document, will typically work with less "friction" when you don't have to maintain two different systems with overlapping capabilites.
On the other hand, you have to think about if these advantages outweigh the easiness of your Wiki. The edit/generate/refine edit/generate again circle may be quicker with your Wiki. I guess that you can get that cycle quite fast with doxygen keeping your overview pages as a separate doxygen subproject. You can make use of the external linking capabilities of doxygen, which is not a replacement for a "quick preview", of course, but a step towards that direction. I have not done this by myself, so far, but I guess you must try that out for yourself if you want to know if it works in your case.
Concerning other projects: I think a tool like doxygen is primarily for library documentation. If you are not a third-party library vendor, and everyone using your libraries has full access to the source code, then the need for a tool like doxygen is questionable. In our team, for example, we have almost no external docs outside of the code except end user docs and the docs of our database models. Our primary tools for that kind of documentation are docbook and fop, which gives us satisfying results.