What program do you use to write technical documentation?

Question

I'm writing an architecture/technical documentation for an inhouse project and I'm becoming more and more frustrated with Microsoft Word as I seem to use most of my time getting things to align correctly. Word has horrible usability issues but I didn't come here to rant, rather I'd like to know whether there exists something more suitable for the job.

The point of this documentation is to provide a "big picture" of the system, and as such I'm not generating documentation from source code but rather writing it all by hand.

Are there any alternatives to Microsoft Word for writing properly formatted technical documentation with less frustration?

Answer 1

It depends if you want looks or control. I prefer python sphinx: http://sphinx.pocoo.org - you write docs in rst ( http://docutils.sourceforge.net/rst.html ) and then compile them into format you want - html, pdf or other.

So you will have to write docs from hand, and you get nice looks and usability just while writing/codding in rst format.

Sphinx written docs sample: http://docs.python.org/

More at http://en.wikipedia.org/wiki/Sphinx_(documentation_generator)

Answer 2

If you don't use much diagrams, learn LaTeX. It will take a while to get to know it good enough to use it, but you never have to care about indentation again because it's written with the WYMIWYG (What You Mean Is What You Get) principle. It also has perfect possibilities to include pieces of source code, or auto-referencing to existing source code.

And packages for software documentation solutions have others already crafted for you.

Otherwise, doxygen is a good option - but as the name says, it is more used for generation of documentation (more like JavaDoc) - and I don't think you're looking for that.

Answer 3

I put it in the company's wiki.

If you're wondering which wiki software is best for you, there's already question about that: Good Wiki Software for IT Company

Answer 4

I understand your frustration. I can't begin to count the number of times I found myself frustrated with software attempting to be 'too smart' and end up wrecking my document. Word is one of the top instigators, I admit, but I haven't found an better suited replacement for writing my documents in.

To answer your first question: What program do you use to write technical documentation?.

1. Microsoft Word - I keep using this although sometimes it makes me scream. I'm afraid I have used it often enough to know the issues and have found a way to work around them. I use it mainly for technical documentation not containing too much other then explanation and additional images. I can also paste flowcharts from Visio - which is an awesome plus.
2. Microsoft Visio - I found this to be the absolute best when it comes to creating visual representations like required for UML. It, like Word, sometimes thinks too much, but other software usually thinks too little. Visio lets me work quicker and more efficient - even with some issues that it has.

For your second question, alternatives.

Alternatives for Microsoft Word I have used/tried:

1. Google Docs - This is alot more basic, avoiding most of the annoying markup issues word has. It just works. The main problem I have with Google Docs, is that it is Google Docs.
2. Open Office - It is free, but not as smooth as Word, and comes with some of the same annoying problems. I wouldn't suggest this - but perhaps you could try.

Alternatives for Microsoft Visio I have used/tried:

1. StarUML (here) - Some people inside my company prefer this over Visio. I think it is too basic - causing me to click/drag alot, which makes me inefficient.
2. Numerous others - Somehow they all lacked having all type of documents I'd like to create.

I have added some additional explanations, since my unedited post was short and brief.

Answer 5

What I use

I've recently re-discovered Graphviz which is excellent for knocking up quick automatically formatted directed and undirected graphs.

After years of trying to coerce Visio to do simple diagramming quickly, it's really refreshing to know that a few lines of text can give you all you need for the simplest of diagrams, and even quite complex graphs can be built up quite quickly.

For a quick look at the sort of things you can do with the dot language, check out the Gallery.

Other benefits

Also, like rst (mentioned by JackLeo) the graph data is stored as simple text files, so it is easy to edit in ordinary text editors and easy to keep in your source code repository along with your code.

In my experience, the closer technical documentation is to the code, the more likely it is to be kept up to date, and if your documentation builds along with your application, it's even less hassle to maintain up to date versions.

Answer 6

I personally love storing technical documentation on a wiki. They allow collaborative work, backups, search features and many offerings can export to Office formats.

Invest the time and server space to set up a Wiki. If you have the money, Confluence is a great investment. http://www.atlassian.com/software/confluence/

Answer 7

Docbook is a good format for technical writing.

The format is based on XML, and can be used to generate html, pdf or online help. Its text-based nature allows it to be tracked in a version control system.

To edit a Docbook document, you can use a text editor, an XML editor, or a dedicated application. I personnaly use XmlMind.

Dita is another format you can use, similar to Docbook. There is also a Simplified Docbook, fully compatible with the original format.

In short, these formats defines high-level structures, such as chapters, paragraphs, notes, legends, listings, links, emphasis, etc... So, when you edit the document, you only focus on the content.

If you need to precisely paginate the document, or if you absolutely want to apply specific formats (font color, font size, alignment), then these formats are not suited to your needs.

Answer 8

I wrote a blog article last year on this very subject, describing how I set up my new toolchain to create HTML and PDF output from simple, easy to edit, VCS-friendly text files. I use Asciidoc, Docbook, Saxon and FOP. Works well for me, and is much nicer than LaTeX or editing Docbook directly IMO.

You can find the full write-up here: http://www.stevestreeting.com/2010/03/07/building-a-new-technical-documentation-tool-chain/

Answer 9

LyX is pretty nice. It was mentioned in a comment on the LaTeX answer, but I think it deserves its own answer.

It's basically a GUI around LaTeX based on the principle of WYSIWYM. While the final result might look a bit different than what you see on screen it's close enough to get an idea of what it'll look like.

As a GUI it also makes sure you don't have to remember all of the LaTeX command names, which is nice :).

Answer 10

Another option (especially if you're in the Ruby world) might be JDoc, which is a very simple documentation framework that lets you use widely-supported markup and put it under source control. It lets you edit the documentation in your text editor of choice (my personal favorite way of doing things), and it supports:

• Markdown or Textile
• syntax highlighting
• easy internal links
• a hierarchical documentation structure (useful for large projects)
• customizable styling and structure (but it looks nice out of the box, too)

It generates static HTML, so the resulting documentation is easy to host and doesn't have much of an impact on your server load.

For an example of it in action, check out wpmvc.org.

Answer 11

You are right about MS-Word. It was designed to let relatively unskilled people produce professional-quality documents for paper publication. Your skills and goals are different.

Your documentation will almost always be read on a screen, and not on paper. So there's no need to worry about formatting for paper. To speed the writing process, you want a tool with simple inline formatting. I work in a small shop, and the second thing I did was set up Trac. Wiki markup is easy to learn, unobtrusive when composing, and more than adequate for internal documentation. If your documentation is mathematical, you can install a plugin so you can format math via TeX.

Answer 12

Personally I use Adobe InDesign.

It is not the ideal choice for composing text, that would be Microsoft Word or Corel WordPerfect (for grammar, spelling, etc.). However the control over layout and positioning of all types of elements (vector, raster, text) is unmatched.

I come from a printing and design background so InDesign was something I knew very well before switching to software engineering.

Answer 13

I've never seen anything that could beat FrameMaker at technical docs, but it was pretty pricey and required a high-end workstation (back when that meant a Sun-4 or Apollo). The version I used ten years ago was far superior to today's MS Word for tech docs. The way it handled multiple figures, graphs, footnotes and page references was like magic.

Answer 14

Try screensteps:

http://www.bluemangolearning.com/screensteps/

Answer 15

I recently began using Scrivener for all my large writing projects. It was developed as Mac Software for Novelists but they have recently released a version for Windows. It is designed in a way that it is easy to keep everything organized and when it is ready to be published it compiles everything into a document in a format of your choosing. The best part is that it only costs around $50 or so. I am hoping to use it to design my next big software project.

http://www.literatureandlatte.com/scrivener.php

Answer 16

In spite of its cost, I think Confluence is a great tool too for writing technical documentation allowing you to handle versioning of your product very nicely amongst other benefits.

Answer 17

I use Docmenta. It's free of charge and provides a web-application frontend for the docbook stylesheets.