What tools do you use to write/maintain/manage software documentation?

Question

What tools are available out there to make writing and maintaining software documentation easier? Specifically what do you use to document requirements? What do you use to document your design? What do you use to document how your software is tested? How do you trace requirements back to your design and test documentation? Or is all of this documentation overkill anyway?

Answer 1

Notepad, Microsoft Word, and Visio or UModel are my standard documentation tools.

Whiteboards + Cameraphones + Fax Machines factor in there somewhere as well.

Answer 2

Word + Visio + SVN + TRAC

Edit:

And yes, I believe it's overkill, especially since it's near impossible to merge binary format documents. They therefore quickly get out of sync with the code development processes.

Documentation is important at the start of the project, but in my experience, that's mainly to make sure the "contract" understanding is solid and there is some tracibility on that understanding. If you write documents for the system, make sure you plan to maintain them as well, so choose tools that support easy maintenance. "How to" style documents are easily maintained using a TRAC wiki page. Reduce the need for many documents by getting your app to document itself as much as possible. This means proven development processes, automation, code (re)views, and intuitive UI's!

Answer 3

Always with LaTeX. There are a lot of templates for everything.

Answer 4

I recently discovered Code Visual to Flowchart, it's able to take code in a variety of different languages and translate it into a pretty decent flowchart, which you can then export to Visio, Word, several other formats. It's made analyzing and optimizing some spaghettified code easier, and I plan to use it further to document existing stuff once I find the time.

In general I find it's not worth documenting something in great detail until after a particular system you've built has had some shakedown time and been in production for a while. Documenting initial concepts and design related to a project are very handy though, because if some stakeholder whines that something isn't going according to spec, you could refer them to a particular document from a particular date and show them the specifications that you were going by at that time. Revisions would shortly follow, but there would be a paper trail rather than you potentially getting roasted for a perceived miscommunication.

Answer 5

Microsoft Office:

• Word for requirements, use cases, test cases specifications, etc.
• Excel for traceability (in some degree), or some reports (e.g. test results)
• JUDE for UML documentation (kept to a minimum), combined with Word documents for overview of technical solution, etc.
• Doxygen for code documentation

I use to trace use cases to requirements by a simple excel file, having rows with use cases and columns with requirements id (or at least requirements sections). Unless a very complex set of requirements and a very detailed traceability is needed, the solution works fine.

Never tried to trace a design element into a requirement item. But did it for testing. Test cases were associated (through an excel matrix) to the use cases, which were associated (through another excel matrix) to the requirements.

I should mention that the traceability ensured this way wasn't very detailed, but enough to fulfill the needs of the project(s).

Answer 6

We have reference docs for our entire system automagically built by doxygen. For more explanatory documentation, I like to use HTML in a group-wide wiki. That way when someone else notices something wrong or lacking, they can fix it.

Answer 7

In order of importance:

• Comments in the code
• Visio diagrams
• MS-Word documents

Answer 8

Our team uses an internal wiki to capture user requirements, high level code documentation, and support / troubleshooting procedures.

We use a couple of different setups depending on the project. Lately we have been using the wiki that comes with trac, however in the past we have also used Team Foundation Server which includes an instance of SharePoint.

Using a wiki has allowed us to:

• Work independantly on different parts of the documentation without trampling all over each other
• Visibility: All of the documentation is visible to all memebers of the team at all times
• Searchability: If I have a question on something I can type in a search term and hopefully kick up the proper documentation.
• Central storage of all of our documentation: No longer are documents located on each team members' computer, so in the worst case scenario something happens to a person's computer we have all of their documentation up on the wiki, on a server that is getting backed up nightly.
• Allows each one of us to correct an incorrect information we find in the documentation very quickly.

As far as tracing requirements from code to documentation I have tried to use NI Requirements Gateway. The major issue I encountered is you need to conform to how NI Requirements Gateway expects to see the requirements documents, and customizing it to how your documents are formatted is maddeningly difficult.