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.
Welcome to the drop-dead boring side of software engineering, reverse engineering products you already have!
This is largely a job to make it look like you know what you're doing and the company isn't incompetent enough to skip a crucial step of the process, even though they are. In theory, any sort of documentation will help other programmers step into the project later, so if you find anything that was confusing to you, write out an explanation about it after you figured it out.
1) You're absolutely right. Most documentation (should) come before the product is made. Things like requirements, design, testing. Others however, are expected to be made afterwards; users manuals, traceability, QA checks.
2) If the customer is asking for it, you should take the dive and produce the documentation they want.
3) There are a lot of different templates out there. Google around for SRS, software requirements specification, SDD, software design description, or even DO-178 templates, if you want to be buried in paperwork till the end of your days.
But by and far, do enough paperwork to make the customer happy, as you've already missed the boat for it's usefulness. Unless, of course, this project has a long life ahead of it. In which case, you should really get on top of it before it grows to something unmanageable.
Best Answer
I'd go with:
#6. Declarative: ...
Rather than say "The reason this was done is because each Foo must have a Bar", just say "Each Foo must have a Bar". Make the comment into an active statement of the reason, rather than a passive one. It's generally a better writing style overall, better fits the nature of code (which does something), and the
the reason this was donephrase adds no information whatsoever. It also avoids exactly the problem you're encountering.