Slashdot Mirror
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?"
I get my lawyers to do it; they're my writting machines.
"Elmo knows where you live!" - The Simpsons
I like ballpoint pens.
(thought I was going to be getting a pen discussion until I read past the headline)
If you find a good spellchecker, let the Slashdot editors know... (Manual Writing Tools.)
Well, that clearly tells us that this guy's looking for "writting" system that at least supports spell checking...
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 is awesome for technical writing.
Or more precisely: What do you need that OpenOffice 2 doesn't provide? You're obviously not into Docbook, because that would be the obvious choice for freaks who want to do their editing in VI/Emacs/Nedit/Jedit. The Blender folks did that with the Blender 2.3 manual. And they hated it. Now they're back to open source word processing.
Honestly, if you want ease of use, felxibility and power, I strongly suggest using Open Office 2 and the features it provides, such as indexing, data source linking, DB frontends and Forms, etc. Otherwise - if you are a Browser oriented shop - just use one of the countless wikis or - if you all dig the command line and your favorite editors - continue using XML (Docbook or whatever) but beef up your editors with XML plugins, extensions and macros. It's not that difficult, is it?
We suffer more in our imagination than in reality. - Seneca
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."
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 (I'm pretty sure this is available for Linux & Windows too)
Mellel, which has some very good reviews
Manuscript
Which may not be as full-featured.
Can anyone tell me how to set my sig on Slashdot?
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
Bastard Operator From 193.219.28.162
First of all, we have no idea what format the book is to be in (print, pdf, windows help file, etc). Each different format requires different software/knowledge. Without this information, it's pretty hard to recommend anything.
However, as a tech writer with years of experience, if you don't know much about writing or structuring manuals, I would probably default to the defacto FrameMaker package. It supports Docbook, unstructured and structured (SGML and XML) tagging, and it fairly easy to get going with. If you outgrow it's functionality, you can buy one of many packages for macro editing and automation of repetitive tasks. Adobe has a free program to help you do some of these things, but it's very similar to coding C and may be a bit overkill.
As a last resort (and if you have access to people who know how to create or modify a DTD for your use), you could buy a package such as Stylus Studio for editing code and creating XLST files for automating tasks and formatting the document. Unless you have experience, this will be overwhelming.
If you need online help, well, you'll probably use RoboHelp like most everyone else.
As far as any more advice than recommending the software packages, I think we really need to know the scope of this project (length of book, what type of information is involved, how much of the book is tabular data vs. instructional data, etc). Personally, I have about 5 different software packages at my disposal and use a each on a case by case basis depending on use.
Wise men say, "Forgiveness is divine, but never pay full price for late pizza."
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.
He asked for "Manual," not "Automatic," writing tools. You should be recommending pencils, pens, and mechanical typewriters.
I don't think I've ever seen a 0.05 mm lead. maybe .5 mm, which is what I use, although I think they still .3 mm also. As far as the sharpness goes, yes, it does require the pencil be rotated every so often , but that can be solved by just learning to get a rhythm, and rotating it before it gets to the point of being too thick. This also helps the contrast problem, as it usually shows up darker when you're writing on the sharp edge. You definitely won't get anything as good as a pen, but it's a trade off. I'd take the erasability of a pencil any day, over having to futz with whiteout, or having to cross things out. I find that I actually like the resistence given by a pencil, and find pens to be too smooth. I guess it's all just personal preference, but I don't really understand the appeal of pens, except in circumstances when you don't want something to be erased, like when you sign your name to something.
Anthropic principle: We see the universe the way it is because if it were different we would not be here to see it.