So I was asked this question recently about documentation, and what the best method was for generating it (auto or otherwise).
Here is the question…
I think people try to autogen docs from tests, but we at XXXXXXX try to automate docs from specs. Not sure this is legit. Thoughts?
Initially I had included my actual response when posting this, but after re-reading it, I don’t think it made as much sense as I thought it did. However, my more complete explanation below makes far more sense, and I think is more accurate.
If you look at my initial post, or talk to me for any amount of time, you will understand that I am all about the users experience. That includes both the application, as well as the documentation. Any docs you provide to an end-user should be written with them in mind, regardless of where you got the base information contained within them. If your target audience is very technical, docs that were auto-gen’d from tests are probably a pretty good start. If your target audience is Betty from accounting, then you are probably going to want to start with the specs and flesh out from there. Tests don’t always take into account the user (they usually do, but not always), so you need to account for that aspect when using tests to auto-generate. Conversely, specs are not usually very technical, and as such would probably not be much help to the more technically inclined. Regardless of which you choose, remember that anything that is autogen’d is only as good as the material it is being generated from.
At the end of the day, it is important to remember that regardless of what you used for your source, the documentation you produce should be useful to the people that will be using it. The whole point of documentation is to help your clients use your product more effectively, and to reduce their dependence on you and your support staff. It is quite possible that you may need to do both types of documentation, or some blend of them. Their is no globally correct answer to this question…it is all going to depend on who will be using said documentation.