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

3 of 139 comments (clear)

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

    1. Re:"Manual" you say? by GospelHead821 · · Score: 3, Interesting

      That was my first thought as well. A while back, I got into several lengthy discussions about handwriting implements. I am quite fond of the Pilot G2 pen. The ink smears a little bit, but the colours are vibrant, the cartridges are easy to obtain, and they are also used in the Dr. Grip series of pens, which are very comfortable and stylish. They're also the only gel ink cartridge I've ever used that doesn't dry up in the tip and clog the pen if you don't use it for a few weeks.

      I'm definitely an anachronism when it comes to writing. I really enjoy writing letters: with a real pen, in longhand, on fancy stationery, to be sent by postal mail. I know a lot of people who lament the loss of grammar and spelling that the age of instant messages has brought upon us. In addition to those, I lament the loss of penmanship and the "human" factor that the word processor has wrought.

      --
      Virtue finds and chooses the mean.
      Aristotle, Ethica Nichomachea
  2. Lyx Editor and LaTeX by imagineit · · Score: 3, Interesting

    I was also searching for a better way to create technical documenation and stumbled upon Lyx http://www.lyx.org/. It is a WYSISYM (What You See Is What You Mean) editor that gives you the power of LaTeX with a GUI frontend. You will find it truly amazing how fast you can write when you are not concerned with the layout of your text.