Technical Documentation Format?

Factual Questions
1

I need to write some technical documentation on software for a company I’m starting. I’d like to write it in a format that will allow me to generate different kinds of output (HTML, PDF, etc.) from the same source file. I’m currently looking at DocBook, but that seems a little bit unpolished - is that opinion unfounded?

What do companies like Oracle use for things like this? Their documentation is available in a bunch of different formats, and seems like it was generated from one source (the typos are the same).

Being somewhat short on funds, I’d prefer if the software was free or at least low-cost. It doesn’t matter which OS it requires, although it’d be helpful if I could edit the source files on Windows. And of course, the output has to look fairly professional.

If anyone has any recommendations or could point me in the right direction I’d appreciate it.

2

I’ve been a professional technical author for 14 years, for 7 companies in the UK, France and Germany; and single sourcing is a pet topic of mine. I can unhesitatingly recommend AuthorIT. You can produce Word documents, HTML, compiled HTML, Winhelp and other outputs from the same source. It’s absolutely wizard.

It provides you not only with single sourcing in the sense of “one source, multiple formats of output,” but also in the sense of “one topic, multiple locations.” Since everything is an object in a relational database, chunks of text and graphics can belong, virtually, to as many books as need them; for example, if you have two Word documents (or help files, or HTML pages) sharing the same information, you need to create that text only once. Changing repeated information then becomes an absolute doddle.

It will cost you around £250 (in the UK - not sure about other countries) for a single licence: but for the time it will save you, the professionalism it will lend to your documentation, the painlessness with which you can maintain large volumes of material in multiple outputs, it will pay for itself many times over.

If this sounds too much like an advert, please be aware that I am nothing to do with AuthorIT. It’s simply that, of all the tools I’ve used during my career, this is the one that’s really knocked me out.

For more information, see www.authorit.com

3

You could try XML format. XSLT will allow you to transform any XML document to HTML and PDF formats. However, you have to learn how to use XSLT, which is not as easy as choosing “Save As” from the “File” menu of most programs.

There are commercial products like XMLSpy which will help.

It’s probably not what you were looking for, but I thought I would suggest it.

4

Then, too, you might want to learn TeX or LaTeX and have your computer typeset your text for you. The document can be converted to PDF or HTML with no trouble.

TeX and LaTex make it MUCH easier to consistently format a document than Word. Word lets you do things like manually setting a character attribute like this rather than making you define a text type (say, chapter titles are of a certain size, in a certain typeface, and are automatically included in the TOC.) With TeX, the amount of work to be done whether you manually format each piece of text or use a text type is about the same - but since you get better results using text types, most people just go that way.

Yes, you can get the same things out of Word. Word sort of incourages the manual format thing, though. Defining a text type gets you into digging through piles of pop up windows and index tabs. It is just a pain the ass. Also, you will most likely hear horror stories from people who have tried to make large documents with Word. I won’t repeat them here.

TeX documents are created in a plain text editor and post processed to create a DVI, PS, or HTML document. TeX and LaTex have sets of settings for doing different things - like books or magazine articles or DIN standard letters, etc. - that let you concentrate on your text rather than the formatting. If you use one of these, then you don’t concern yourself with how a chapter title looks, you just insert a tag in your text to mark a chapter title, and TeX does everything else.

TeX makes it easy to get a professional looking document. The predefined things have been tweaked and tuned over the years to provide results much like you would get by having it typeset by a professional. Things like generating and index or a table of contents are trivial. Pictures inserted in to the text get that text book “see figure 5” text and the pictures are labeled automatically.

In short, the software is geared to make producing a clean looking document easy.

I will tell you, though, that it is not at all like using Word. It is NOT WYSIWYG. Your text more closely resembles HTML source code than anything else. You won’t see how your document looks until you process it and view the finished output file. On the other hand, you don’t get bogged down in trying to force figure to stay on a specific page so that your manually generated table of figures stays correct like you might with Word. God, the stories I could tell about pictures not staying put in a Word document.

Anyway, my two cents.

5

<Snip>
On the other hand, you don’t get bogged down in trying to force figure to stay on a specific page so that your manually generated table of figures stays correct like you might with Word.
<Snip>

Oh, God, you’re making life complicated for yourself! Manually generated table of figures?! Try Insert/Index and Tables… then, from the dialog box that appears, Table of Figures.

6

My advice to you about LaTeX: if you’re a complete TeX/LaTeX neophyte like me, then, to paraphrase Mort Furd, you’ll be concentrating on getting your document to compile rather then on the text. (speaking from personal experience :smack: )

True story: I once took a class where assignments were required to be submitted in LaTeX. I successfully got ASCII art added to the list of acceptable formats because it was easier and less time-consuming.

To be fair, I do recognize that it’s a standard in many circles and can produce professional results. The learning curve, especially going only with freely-available references, was rather steep for me though. YMMV, I suppose.

7

I’ve used the automatic function in Word, too. It worked about as well as manually generating the damned thing - and it is about as reliable.

We put out a manual for a piece of software where I used to work. We were required to use Word. I lost hair and nerves getting the damned thing done - mostly from figuring out how to work around Word bugs in functions that should have been solid.

Automatically generated page numbers that weren’t correct, diagrams that wandered around. Table of contents that changed without notice. Footnotes that got put one the wrong page, etc, etc, ad nauseum.

**Garnet:[/b)
It may be true that you spent a lot of time getting your TeX document to compile correctly. On the other hand, you can type your whole text, format it when the text is complete, and then worry about the compile. Three seperate tasks that can be performed sequentially - and which are much easier to handle when done that way.

8

Let me discuss, from 21 years experience with tex/latex, some of the pros and cons. I will try not to make too much of the fact that I would never use anything else. After all, I have 21 years of experience to call on.

Cons: There is no getting around the fact that it is hard to learn. You must buy one or several books since there is little online help (although the source for the texbook is available, but it is supposed to be used only for examples).

It is not WYSIWYG. You have to first edit, then compile, then view.

The error messages are, not to put too fine a point on it, feeble.

You provide your own editor, although there are free ones available.

The font choices are, unless you choose to pay for them, limited.

Pros: The output is superb; I have published three books using it and you simply do not notice they are generated on a microcomputer. One of them is available for free download; anyone who would like to see it may email me.

Everything I have written in the past 21 years will still compile; the current version of 1989 was basically a bug fix (with a couple minor features added, mainly to accomodate foreign languages) of the 1982 version. Try loading a ten year old Word file.

Although it handles any text well, it is optimized for technical, especially mathematical, work.

It is trivial to convert to ps or pdf output. There are html converters, but I have never tried them. For web posting pdf is the way to go.

You provide your own editor, although there are free ones available.

It is available for every computing platform I am aware of.

There is no cheaper program available. (It is absolutely free, although it is possible to buy it along with considerable hand-holding.)

That’s all I can think of for a while. I would recommend it for someone who will be using it for long enough to make the learning curve worthwhile, but not as a one-off project.

9

Whatever you do – whatever you do – don’t don’t don’t use Word. I’ve sat in your shoes in a fledgling software company. We needed docs, and I ran engineering and one of my guys didn’t spell too bad, so he became the writer, and he knew Word, so Word it was.

Everything was fine for version one. Even the second version was fine. But as things progressed, Word fell apart. Weird problems that we couldn’t find work-arounds for. And of course there was no time to transfer everything to another program.

The company grew, and eventually we had 3 full time writers, and the thing was still in Word and everybody was unhappy. And as their boss, guess who the writers were unhappy with? Then, of course we forced a transfer of the documentation into the schedule, and of course it ran over schedule, so guess who the rest of senior management was unhappy with?

You didn’t mention Word, but if you even consider it, please take it into advisement: Stay away.

Thanks for letting me vent. It’s been bottled up a while.

10

Oh… What we transferred to was FrameMaker. And everybody was happy. The next company I started, I ran engineering again, and we went with FrameMaker there as well. And everybody was happy.

Can’t say I have extensive experience in the technical writing field, but I have managed several writing teams now (and done a fair amount of product writing here and there), and FrameMaker has been a winner for me so far.