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