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

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

[__aaclcg7560]

Yeah. I missed the old Pilot felt tip pens of yesteryear. Although recently Pilot came out with a "liquid ink" (not gel ink) pen using a plastic tip that's writes similiar to the old felt tips.

Re:"Manual" you say?

[martinultima]

Personally, I'd say my favorite Pilot pens are the Precise ones – you know, the nice solid tube-shaped ones that you can get in a four-pack at Wal-Mart for just a couple bucks. Although my absolute favorite pen is probably one which my dad and I turned on his lathe – it's a bit chipped, because it was the first pen either of us tried turning using a "fancy" pen blank and not regular wood, but it's really neat looking, and I'm right now using it to write a novel (I've been writing the entire thing by hand, one section at a time, just randomly ordering things around – after I've got enough sections together I'll write some stuff to connect them all and then type everything up at once. A lot easier to edit that way; I once did write a complete novel, but it's horrible and I'm probably never going to publish it...)

Well, so much for staying on topic!

Re:"Manual" you say?

[GospelHead821]

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.

A spelling checker, for one

[RobertB-DC]

What kind of techniques or tools are there to make writing manuals a bit friendlier and faster?

I'd suggest a spelling checker. It would catch things like "Manual Writting Tools?".

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.

Also, consider physically removing the semicolon from your keyboard. Between the giggles over the misspelled title and the confusion of the above sentence, I have no idea what this article is about.

Seriously, if you want to write something that people will *read*, you've got to keep the human audience in mind -- even if you're just writing program-level documentation. Unless your only goal is to produce a sheaf of paper for the Sarbanes-Oxley auditors, you want your document to be useful for the poor guy who gets stuck debugging the app when the lead programmer gets run over by a bus.

Re:A spelling checker, for one

[rivimey]

I would agree with the need to bear your audience in mind.

Writing good English is just as much a skill as writing good C# or Java. Indeed, you can't just say "good English", as the style matters too... good novel writing, tech docs, journalism, and academic writing are all different styles that must be learnt, and some people are better at one style than others.

Regarding tools, the one that keeps being mentioned as being the best for tech writing is FrameMaker. There is a caveat: it takes time and skill to set up properly. However, once that is done it can be used well by authors who aren't also geeks!

If you feel tempted by DocBook or one of the other XML based systems, I've found the XML Mind XML Editor decent, but with less flexibility than Frame.

MS Word should be ignored -- it is too unconstrained and too buggy for large documents (>100 pages).

Some people really like LaTeX, and it is indeed good even for large documents, but only if (a) your authors are prepared to learn it and (b) your desired output formats are supported. It is supported by Windows as well as Unix, and there are GUI front-ends (by default it is batch processed).

HTH,

single source publishing

[goodminton]

If you're going to produce your manual in both print and online form, AND you might possibly want to re-use some of the manual content for things like brochures and presentations, I'd go with a single-source publishing system like AuthorIT. Single-source publishing was developed specifically for software projects and it allows you to create documentation in many different formats. It also allows you to reuse content across documents, which saves time and reduces inconsistencies caused by redundant content being recreated for each document. It ain't free but I've used AuthorIT for several years now and I'll never go back to producing documentation using Word or OpenOffice.

Lyx Editor and LaTeX

[imagineit]

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.