Can LaTeX be used for producing any documentation that accompanies software?

Question

Although related to this question about LaTeX being used outside mathematics and academia, I'm specifically wondering if anyone uses or is familiar with anyone that uses LaTeX for generating any type of documentation relating to software. If so, could you say whether or not you like LaTeX and the purposes for which you use it? Thanks.

Answer 1

I used it sometimes, but my boss is more into office-documents and if he writes the documentation or parts of it, we don't use LaTeX.

I personally like LaTeX and use it also for software-documentation where appropriate and where I'm in the position to decide it myself.

Answer 2

Having extensively used LaTeX and also written software documentation, I would say that the strenght of LaTeX is a very flexible typography system, such that switching templates and formatting is very straightforward, and that writing math is pretty quick. I don't think that either of those strengths is particularly useful when writing documentation, because documentation needs lots of screenshots and step-by-step instructions.

The biggest problem I have with LaTeX, at least TeXShop on the Mac, is image formatting and placement. The tools in MS Office or OpenOffice are far more useful for that. The ability to change the typeface is good only when publishing to different journals; consistent documentation design can be easily handled by templates and the like in office software.

Plus, more people are used to office software than LaTeX, so the training curve is smaller. So when the next person comes along and needs to update existing documentation, they can get started right away, rather than also having to learn LaTeX.

Answer 3

Some big open source software build they documentations from scratch. Perl documentation system (POD, a man-like documentation) supports exportation in LaTeX, which I used sometimes to print it.

Answer 4

I haven't used LaTeX since I stopped being a mechanical engineer. I know it's used extensively for typesetting papers with mathematics. Anyone who submits a paper for consideration by an ASME journal is certain to use it. I used it to typeset my dissertation and loved it.

But since then, I've seen nothing but Word, without a single exception.

Answer 5

Many projects in the Python ecosphere are now using Sphinx to produce their documentation. LaTeX is one of the many output formats that Sphinx can produce. I believe that Doxygen, a C++/C/Python/Objective-C/.. documentation engine can also produce LaTeX output.

In general, projects where a hard-copy documentation format is required or where documentation necessarily contains a lot of mathematics benefit greatly from LaTeX-generated documentation--these are, afterall LaTeX's speciality. LaTeX on its own is a general typesetting system, not a code documentation generator, so I would recommend using a package like those described above for generating code documentation in LaTeX. Using one of these higher-level systems will greatly simplify the task.

Answer 6

GNU Troff (Groff) seems to be more popular than LaTeX in the software community. According to Wikipedia, O'Reilly uses it for its books too.

Answer 7

I mostly write academic papers with LaTeX. However, my research has to do with software documentation, so I actually deal with some of these concerns.

The best thing about LaTeX is that you are concerned with content and structure, not just visual layout. This is like writing HTML with CSS rather than pure HTML.

Here are a few reasons that I think LaTeX is useful for creating some documentation:

One reason is that dealing with multiple styles is more structured and styles are more "logical" than "visual". For example, if you are typing in Word, every time you want to mention a class or object, you change a style. In LateX, as I type, I write something like:

bla bla bla~\methodName{foo} bla bla~\className{FooBar}.

I find that for long documents, this is useful. I can easily find my class names, change them, etc.

A second benefit is that I can use macros for entities. For example, suppose that I have some module that handles some functionality, but that its name may change later or that I'm not sure what it is. I can have a macro called \ModuleForXXX, and when I eventually pick a name or change it.

A third and perhaps most important benefit is that it is easier to create a document from a hierarchy of files in LaTeX than in a Word document. I typically have a main file that then includes other files, that then include other files and so on. I view it hierarchically (at least on Windows with WinEDT), and I can easily rearrange the order of things just by changing inclusions. Needless to say, I also use includes for the actual content of code excerpts and documentation text.

LaTeX has several drawbacks though: 1) Few people know it and some people who are used to Word just resent it. However, for someone who reads a final PDF, it shouldn't matter. 2) Image placement can be a little tricky, though you can override options and force LaTeX to listen to your instructions. 3) It works best with a dual monitor configuration.

Answer 8

There is Knuth's CWEB system that uses TeX. http://www-cs-faculty.stanford.edu/~knuth/cweb.html

Answer 9

The Insight Segmentation and Registration toolkit (www.itk.org) has a very cool system where the LaTeX source is placed in the source code comments and they actually genereate a several hundered page programming guide from it.

Answer 10

I've used it for software documentation and it works quite well for this. One of the key benefits is the ease with documentation from multiple sources can be integrated. You can (for example) render an API reference or a data dictionary to LaTeX and cross reference other parts of the specification to it. If you can put LaTeX snippets into the API comments the XREFs can even go both ways.

LaTeX is also very good at maintaining indexes, TOC entries and other such items, so the quality of the document content is much better than with tools such as word. The cross references, index entries and anchors are much more stable.

Answer 11

I've helped setup LaTeX for documentation purposes in a former company. It worked but the technical writers disliked it.

The main complaint was that they felt it was bondage. Which was a good thing, they couldn't mess things up too much.

It was quite a bit of work to setup the document class to be just right and placement of images was never perfect in all cases but the final documentation was just beautiful. I'd do it again if given the choice.

I wasn't a LaTeX guru then (and still not now), but you will need someone knowledgeable in LaTeX to setup and support such an endeavor as most tech writers are not interested in learning the innards of LaTeX to support themselves.

Answer 12

I am just discovering what a pain it is to produce full-size circumflex (^) and tilde (~) characters in LaTeX. Which are kind of handy for typesetting source code in languages like C.

Here is a description of the contortions apparently necessary for the tilde; I've just asked a similar question on that board about the circumflex.