Manual Writing Tools?

Saulo Achkar writes "I've been recently assigned the task to rewrite the user's manual to a piece of relative complex software. Today, the existent manual used was developed with reStructuredText, a very nice piece of software; unfortunately, we're not able to create classes or templates for things like similar interfaces (that share the same functions), which means we need to write more code and that means more editing. XML formats aren't very friendly to code or edit in, either. What kind of techniques or tools are there to make writing manuals a bit friendlier and faster?"

Comments

Lawyers

[albalbo]

I get my lawyers to do it; they're my writting machines.

"Manual" you say?

[Fallingcow]

I like ballpoint pens.

(thought I was going to be getting a pen discussion until I read past the headline)

Re:"Manual" you say?

[Anonymous Coward]

I'll take 'penis mightier' for 500

Manual Writting Tools?

[ozbird]

If you find a good spellchecker, let the Slashdot editors know... (Manual Writing Tools.)

Re:Your #1 site for quality editorial work!

[DrMorris]

Well, that clearly tells us that this guy's looking for "writting" system that at least supports spell checking...

some ideas...

[tjr]

In my previous job, I wrote a lot of documentation using a program called Help and Manual. I can't say that I thought it was wonderful, but it was functional, especially if you need to make Windows Help files.

Something similar is a program called RoboHelp (from Macromedia now, I think? They've been bought out at least once). It was very similar to Help and Manual in core concept, only a lot more complex, and a lot more expensive.

If you DON'T need Windows Help files, I personally like using LaTeX and Texinfo (from GNU). These are both great for making PDF; Texinfo makes pretty good HTML by default, and LaTeX can be converted into at least decent HTML. I've written a fair bit of documentation for the GNU Project using Texinfo; it seemed kind of "bleh" to me at first, but after a while I got to where I liked it. (And yes, at least Texinfo CAN be converted into Windows Help files of some sort, but I have yet to see this process really work well, at least for what I needed out of it.)

LaTeX

[calumtdalek]

LaTeX is awesome for technical writing.

Re:LaTeX

[bunbuntheminilop]

++

Lyx is a good frontend for Latex too. Its no subsitute for writing it by hand, but then again, there is no subsitute for Latex.

Writting - not what you think

[Anonymous Coward]

Yeah - you need to make writs... A technical term that sounds like it's a misspelling (mispelling :D ) of writing but is actually for creating writs. In fact, the English "write" is really just an evolution of a word "to writ". Similar to how "God be with you" became "goodbye" and "fare thee well" became "farewell", the verb "write" came from the middle English "writ". In fact, "writ" and "red" share the same etymology. It's actually from the Saxon phrase "writ and blood", which means a contract and originates from the custom of bleeding to purge illness. The modern corruption of this is "written in blood". Contracts were never "written in blood" but this sounds plausible to our modern ears than "writ and blood." BTW, the British word "bloody" (as in, "we had a bloody good time") came not from "blood" (sanguina), but from "By Our Lady" (I.e., the Virgin Mary). Anyhoo, the "writtings" is similar to being served - i.e., "The tax evader was writted with a notice posted on his door."

Re:How about Word?

[Penguin Programmer]

They're good at processing words, but _terrible_ at typesetting. Another poster mentioned LaTeX, which would also be my recommendation. It's great for technical writing, you _know_ that your whole document will look consistent (no need to go through and change _every_ diagram or tab stop individually, just change them for the whole docuemnt) and it's easy for a future publisher of the manual to change its look to match how the want to print it.

I use LaTeX for almost everything these days. I can't stand using finicky, annoying WYSIWYG word processors anymore. LaTeX is simply a better way.

LaTeX?

[Gadzinka]

If you used reStructuredText and liked it, but found it lacking in some features, why don't you try LaTeX? I used to manage a rather large documentation for middle size (~50 people) company in LaTeX and found it being plaintext-based a blessing -- all the developers could use all the free revision control systems for documentation as well, without a problem.

I worked in some or other (more or less) Linux shops ever since and now and then, when we buy some product/solution we can clearly see, that some people are still using LaTeX, CVS and similar tools. And I can still see that the documentation looks better and cleaner that the crappy Word "paintings" distilled to PDF we receive with some other software. Sure, you can get the same effects with word processors, if you know them well enough, but I just like my documentation system doing things for me, it's bad enough that I have to write it ;)

Robert