Question

An obvious answer is ‘an internal wiki’. What are the pros and cons of a wiki used for software documentation? Any other suggestions? What are you using for your software documentation?

Loren Segal – Unfortunately we don’t have support for any doc tool to compile information from the source code comments but I agree it would be the best way to store technical documentation. My question was about every kind of documentation tho – from sysadmin type to user documentation.

Answer 1

That’s a very open ended question, and depends on many factors.

Generally speaking, if you use a language that has good documentation generation tools (javadoc, doxygen, MS’s C# stuff), you should write your documentation above your methods and have your tools generate the pages. The advantage is that you keep the source of your text alongside your code which means it is orgnanized in the logically correct place and easily editable when you make a change to the behaviour of the method.

If you don’t have good doc tool support or don’t have access to source code, wiki’s aren’t a bad idea, but they’re a second choice to the above.

Note: I’m talking only about code documentation here. Other artifacts obviously cannot be stored alongside code– a wiki is a great place to put those documents. Alternatively if you use some CMS you can simply commit them in some docs/ folder as text/pdf/whatever files to be editable via the repository. The advantage there is that they stay with the repository if it is moved whereas a wiki does not (necessarily).