Manual Writing Tools? 139
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?"
"Manual" you say? (Score:5, Interesting)
(thought I was going to be getting a pen discussion until I read past the headline)
A spelling checker, for one (Score:3, Interesting)
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 [wikipedia.org] 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:"Manual" you say? (Score:3, Interesting)
Re:A spelling checker, for one (Score:2, Interesting)
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,
Re:"Manual" you say? (Score:3, Interesting)
Well, so much for staying on topic!
Re:"Manual" you say? (Score:4, Interesting)
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.
single source publishing (Score:2, Interesting)
Lyx Editor and LaTeX (Score:3, Interesting)