Slashdot Mirror

← Back to Stories (view on slashdot.org)

Manual Writing Tools?

Posted by ryuzaki0 on from the from-code-to-printed-man-pages dept.

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?"

5 of 139 comments (clear)

  1. Lawyers by albalbo · · Score: 5, Funny

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

    --
    "Elmo knows where you live!" - The Simpsons
  2. "Manual" you say? by Fallingcow · · Score: 5, Interesting

    I like ballpoint pens.

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

  3. some ideas... by tjr · · Score: 5, Informative
    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.)

  4. Re:LaTeX by bunbuntheminilop · · Score: 5, Informative
    ++

    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.

  5. Writting - not what you think by Anonymous Coward · · Score: 5, Informative

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