Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question
    
Open source Python projects tend to put their code documentation on readthedocs. –  user16764 Feb 12 at 18:32
add comment

7 Answers

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).

share|improve this answer
add comment

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.

share|improve this answer
add comment

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

share|improve this answer
add comment

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), manuals. But, the first thing I do, it's to review the code (sometimes from other developers, sometimes, my own).

As a developer, that worked in several projects & customers, I do as possible to add external documentation, 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, its to add some comments to code.

Good Luck

share|improve this answer
add comment

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)

share|improve this answer
    
Thanks for mentioning ASCIIDOC. Will take a look at it. –  Patrick Jun 11 '12 at 15:50
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.