Post History

If you are documenting programming interfaces (APIs), look for a tool that generates documentation from comments in the code.  This allows you to place the documentation right with the code, and the tool extracts the function interfaces from the code directly.  This means there's one source of truth, rather than having separately-created documentation that you copied the interfaces into...once upon a time, and then the code changed but you didn't notice.

Tools like this (Doxygen is one example) are good for low-level "tactical" documentation, but comments in your code aren't enough to provide the overviews, guides, and examples that you'll also need.  For this other documentation, you have two choices: add that documentation into the (for example) Doxygen build by adding documentation files to your source code, or write separate documentation and link or include the API documentation in the published output.

Your decision is affected by the answers to the following questions:

- Who is writing the documentation?  Are the writers trusted to modify files in the source tree?
- Who is the documentation for and how will you publish it?  Do you need to ship something or just post it on the web somewhere?  Or is it internal and you can use a wiki?
- How often do you publish new versions with breaking changes?  If you need to update doc a few times a year, separate API and other documentation is probably fine.  If you're making (and publishing) big changes to the interface in each sprint, that might push you more toward tight integration between the doc and the code.

It sounds from your question like your documentation is for a library of components of some sort.  If that's correct, then regardless of what tool or format you use, find or create a template that you can use to create topics for new features/interfaces/components.  This will help you make sure you covered all the important points and in a consistent order or format.