views:

1680

answers:

14

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.

+3  A: 

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.

Keith
Keith, how do you intergare sandcastle's output with system documentation in confluence?
Shrike
I'm afraid we don't. The API docs built using Sandcastle are for our implementation engineers, while the docs in Confluence are more of a user manual.
Keith
+1  A: 

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.

Kristopher Johnson
+2  A: 

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

Jedi Master Spooky
+2  A: 

Here's what we use:

  • Word - for creating most documents
  • Visio - for creating diagrams as well as Wireframes
Vaibhav
+8  A: 

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)...

Pat Notz
+7  A: 

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.

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).

Herms
A: 

Unfortunately I'm usually stuck using notepad.

Unkwntech
+1  A: 

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.

Wing
+11  A: 
Jim McKeeth
A: 

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.

Matthew Ruston
+1  A: 

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.

krujos
A: 

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.

A: 

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.

jeremcc
Hello, please could you email me copy to [email protected] Thank you very much!
Kirzilla
Hey jeremcc, would you mind sending me a copy of your template? ([email protected])
Chrisc
A: 

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