What tools are used to write documentation?

Question

What tools are used to write documentation?

Specifically for

• User docs
• System administration
• Development

I'm looking for software such MS Word, wiki, TeX (LaTeX, LyX) and for automated tools.

Answer 1

With C# and .Net we have XML code comments that are compiled into help files using Sandcastle.

For user and system documentation we have a Wiki - specifically Confluence.

Answer 2

For user docs and most other forms of documentation, I see MS Word being used most often.

For development documentation, specifically API docs, tools like Javadoc and Doxygen are used a lot. Wikis are good too.

I don't see TeX or LaTeX used much outside of academic or research communities.

Answer 3

We use the Wiki of Fogbugz for general documentation and SandCastle for API.

Answer 4

Here's what we use:

• Word - for creating most documents
• Visio - for creating diagrams as well as Wireframes

Answer 5

We've always preferred LaTeX because our docs have a ton of heavy math... But, more importantly, it's plain text which means it's really easy to manage with our VCS (CVS, SVN, Git, etc.) and it can easily live right there with the code -- so, there's no excuse for not updating the documentation as you develop.

As a nod to Kristopher, we're a fairly researchy organization (though not a .edu)...

Answer 6

I use Visio for generating UML docs and timelines. For me, these are all done during design when I'm trying to figure out how I want things organized, or how things should work. Then, (hopefully) they're updated after the implementation is done so that they match what actually was done (implementation never matches design exactly!).

For code documentation I use a few tools, depending on the language. All of these use variations on the javadoc-style comments, which I like.

• Java - javadoc
• C/C++ - doxygen
• Actionscript 2 - as2api

Visual Studio has a built-in documentation tool for C# (and probably other .Net languages) that uses XML-like comments. I believe others have mentioned that.

For the rest of our documentation (Network protocol, etc), we use a corporate Wiki. We're using Confluence, though there are plenty of Wiki choices out there. We find using wikis to be quite useful, as it's easy for anyone to update the docs when the need to, and it's also easily accessible (no passing Word files around).

Answer 7

Unfortunately I'm usually stuck using notepad.

Answer 8

We also use Sandcastle and GhostDoc, but for UML stuff on the Windows platform, there I have found nothing better in the "free" pricepoint than StarUML.

StarUML is a tremendous value. Development seems to have stagnated for the past 3 years, but it's a remarkably stable tool. I have used other freebies (like ArgoUML), but they have not proven as fast or as fully featured. It's not a replacement for a good commercial tool, but in most places I have worked, no one wants to shell out the money for something like Enterprise Architect.

Answer 9

Confluence and JavaDoc here. Confluence for non project specific stuff like architecture, how-to's, tricks, code samples, some bug reporting, etc, etc.

If it's project specific and not suitable for JavaDoc, I have simply been adding plain text *.txt files to the projects as supporting documentation. It's worked ok so far.

Answer 10

We are way into a wiki (media wiki) for everything from design to end user docs as well as documents detailing our lab setups and who is using what machines. The end user stuff gets imported into acrobat and gets generated into nice PDF's for users (and I think real paper docs still). We use Borland Together for UML modeling (and code generation, but that's another post). We point our testers at the wiki when they go to test a new feature and then they also get to write bugs against the docs as well as the product. I was skeptical at first when we started doing it this way (we used to have writers that we would work with), but have become a big fan. Our users seem to like it as well.

Answer 11

A couple people have already mentioned the C# xml docuementation, and others have mentioned doxygen for C/C++/Java, but I would like to remind everyone that it also supports C# style documentation. It can generate documentation in html, postscript, pdf, and man pages, so you don't need to be stuck with Sandcastle help files.

Answer 12

Word and Visio are obviously the de-facto standard tools. But to make them truly useful for technical documentation, you should have very good templates set up that make formatting it easy. The less you have to think about that, the more you can think about the content. I use a Word document with tons of preset styles... things like section headers, body formatting, lists, code blocks, etc.

In Visio, I use a standard set of Shapes for each type of diagram I want to create (high level system diagram, user interface, workflow, etc.)

I'm actually quite proud of my Word template. It's very clean. I'll email it to anyone who wants a copy.

Answer 13

If you would prefer a special editor for latex, I would suggest texmaker (for linux) or you could just go with emacs ;)