Where to put code documentation?

Question

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?

Answer 1

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.

Answer 2

Use Code Documentation, first. Add Wiki & other methods, if possible

I know that is going to be difficult to maintain it.

Practical answer:

In practical terms, the first thing that developers do, its check the code.

As a developer, I like to have external documentation like Wiki (s) and manuals. But the first thing I do is to review the code (sometimes from other developers, sometimes, my own).

As a developer that worked in several projects and different customers, I try add external documentation when possible, but its common to have a lot of workload and not been able to support a wiki.

Sometimes project managers & other bosses doesn't care about documentation, sometimes others developers don't.

And the best I can do is to add some comments to code.

Good Luck

Answer 3

Some use other systems - take a look at Python's Sphinx for example, they have a all-in-one doc system that build everything (it also works for C/C++)

I always think of documentation as being separate to the code, doxygen is great, but it is for an overview of the API, not 'documentation'. For that, a wiki is great, but I prefer to use ASCIIDOC and store the results of that in source control along with the code, mainly because I can generate PDFs from it to hand to other people (eg the testers, customer, etc)

Answer 4

Doxygen allows you to build PDF, HTML, wiki pages, almost everything you can think of.

My personal preference is to have both Doxygen and wiki and a script or something to check when they diverge.

Answer 5

Since version 1.8.0 doxygen supports Markdown, which should make the experience of writing static pages similarly convenient as in a Wiki system.

Answer 6

Target Audience

I think when answering this question you really need to ask who is meant to read this documentation. A Developer has grossly different needs to a User or even a Business Analyst.

• As a Developer: documentation associated with the code being studied, details such as the interface contract, and examples of usage. Perhaps some high level documentation, and protocol specs for good measure.
• As a User: documentation available via the help menu, or an accessible website about how to use the software.
• As a Business Analyst: documentation available as documents, or as an accessible website are useful. A modest amount of detail about protocols, high-level architecture, and use cases are best.

Maintenance

As to where to place the source for this documentation will depend on your audience, and who is writing for your audience.

• Only have a house of developers? Place everything in the code. It will encourage it to be updated. You will need to work on a culture that encourages documentation updates to be as important as code changes.
• Have a house of developers and documentation writers? Divide the responsibilities. Use the developer orientated tooling for developers, use the documentation writers tooling for the documentation writers.

Where possible ensure that code examples, or use cases can be executed. Automate their execution and internally flag failures. Chances are these pages are poor or bad documentation.

Additionally whatever tools you choose to write your documentation in, you need a reliable means to associate a specific version of the documentation with a specific version of the code. This is still beneficial even in happy cloud land with a single evergreen deployment.

Integrating Documentation

Integration may be needed to produce some documentation, but note that only the user expects a single place to access all the documentation they need.

The business analyst is quite happy with an API spec, Designs Specs, and Usage scenarios to be located in separate documents, or separate sections of a website.

The developer prefers everything visible from the source, but is quite happy to have a couple of high-level design documents, and detailed protocol specification documents external to the code, though preferably within the same checkout.

Your Case

To be honest, the documentation in your wiki is probably not the same sort of documentation in your code-base. It might not make sense to merge the too.

On the other hand integrating the two can be afforded in a few simple ways.

• Source documentation tools (like doxygen) can produce html, and a wiki lives on a web-server. It would be a simple integration point to simply serve a built version alongside the wiki and inter link the two.
• Some wiki products will allow you to run the wiki directly from a file that you can check-in to a code-base. This gives a simple wysiwyg tooling while keeping the documentation paired to the code.
• Other formats such as pdf can be accommodated too, but this will come down to the specific tooling you wish to use. It might make sense to scrape your wiki into markdown files and feed that through doxygen (or other tools). It might make sense to pdf the wiki and source separately and use a pdf merging tool.

At the end of the day, figure out which documentation system has low maintenance costs, and assists you in delivering a high quality product as seen by your audience of Developers, Business Analysts, and Users. Anything that impedes any of these groups will necessarily reduce the products quality.

Answer 7

If you are using ASCII, you should store your hide your documentation data in the high bit of your source code! Then only the most clever (read: deserving) of users have the opportunity to use your docs.

Answer 8

Having documentation in a well defined, easily exportable, portable format might be the real advantage. If sphinx dies (unlikely) I'll just have convert to other system, which I guess would be a scriptable task. Moving data out of wiki (presumably stored in database in a proprietary format might be a pain).