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
... what about sticking with reST and using m4 or other macro package to do repeated tasks?
writting!
in other news, sarcasm is the lowest form of humor.
there is no need to sign your posts. this isn't usenet. your username is right there above your post. stop it.
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.)
Is this some l33t haX0r way of saying, "lawyer"?
By the way, I'm aware that this is going to look odd once the editor notices the mis-spelling of the headline to the article.
Reality is defined by the maddest person in the room
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.
Stressed? Me? Of course not. Stress is what a rubber band feels before it breaks, silly.
Or OpenOffice? Word processors are good at processing, uhm, words... you know.
"It was hell!" recalls former child.
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."
I am a dev on projects that use wikis for documentation. They are great for collaboration, but rather proor at providing a polished website and, as you say, horrendous at printed documentation. They don't tend to be well organized.
I personally compose most of my documentation in LaTeX. But then, I makes use of equations & leverage "legacy" documentation. Most newer projects which don't have math would be well-advised to choose an XML-based format. DocBook and other projects tend to use pdfTeX as a backend for PDF generation, so has many of the same benefits you get from using LaTeX directly. The processors for writing (x)html seem to be more evolved than the equivalents for LaTeX: They're faster, easier, and look better.
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're going to write printed manuals, you might consider using Adobe FrameMaker, a tool designed to handle lengthy documents. (Even Microsoft uses FrameMaker instead of Word for some of its third-party texts.) With some add-ons, FrameMaker can also produce HTML and online Help. In addition, FrameMaker offers a structured mode that allows writers to work in XML.
If you're going to create online documentation, you might consider Adobe RoboHelp if you want to create Help easily. Anyone with experience using an HTML editor such as Dreamweaver or FrontPage will find RoboHelp friendly to use. For a more robust, XML-based solution, you might consider MadCap Flare. In addition to generating a variety of Help formats, both RoboHelp and Flare can produce printed manuals. (Flare's printed documents turn out better than RoboHelp's do, in my opinion.)
As for writing methodology, your best bet is to enroll in a technical writing course at your local university. If you take the course seriously and have an excellent teacher, you can learn much about writing clearly, concisely, and simply.
In the days before OO programming your quality of work was often measured by the quality of your code comments and intelligent use of white space. Readability was seen as one of the requirements for maintainability. Good data structures and clean algorithms followed from that.
Have you ever noticed that code flows better when you can describe what you're trying to do in English first? It's kind of like learning to communicate well with yourself. We used to start with the program comments, in English, then fill in the blanks with code. It worked.
Do not mock my vision of impractical footwear
Yes. Preferably someone who can write. ;)
"I either want less corruption, or more chance
to participate in it." -- Ashleigh Brilliant
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.
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.
Just started out with Vex http://vex.sourceforge.net/. It looks to be a pretty neat XML editor, based on Eclipse, with the DocBook DTD http://www.docbook.org/ built in.
...
I have been a longtime user of LaTeX http://www.latex-project.org/ and have found TeXnicCentre http://www.toolscenter.org/ to be a nice front end for LaTeX. I have tried word-processors, but haven't really played with OO.org long enough to understand the sectioning and styles feature. Now, I recently re-stumbled over LyX http://www.lyx.org/
I think I will stick with LyX/LaTeX till I understand DocBook better.
On a side note, I came across NaturalDocs (http://www.naturaldocs.org/) yesterday. It looks to be a neat way to generate documentation without messing up the whole thing with tags.
Now, it would be a nice idea to take all these diverse ideas and combine them together into a single tool that can work as a driver for various formats (somthing like GCC, which can compile multiple languages). So, you need to know 1 tool, which can parse reST, NaturalDocs, Doxygen etc. You know, the great unified theory of text processing
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.
Planning and writing good, maintainable documentation is not a really simple task. I'd really recommend you find a contractor with real experience to build a workflow to meet your needs. It will probably save you money in the long run. Assuming that is not an option, you can use many of the same techniques you do for coding. Write out a specification for your toolset. What platforms need to be able to edit the docs? What formats do you need to output? Do you need to reuse content? Do you need conditional text for multiple releases (like rebranded OEM versions). What level of training will the writers and editors have? Do you need spelling and grammar checkers? Will multiple people be collaborating on it and do you need versioning? How long will it be? Will it include a large number of graphics? Are their compliance requirements from the government, partners, or handicapped accessibility?
Once these criteria are determined you can evaluate tools. For some jobs OpenOffice or even MSWord is appropriate. For others, Framemaker+Webworks, InDesign, or Quark would be better. For still others Latex or just a plain old XML editor is ideal. Then there are more integrated solutions like AuthorIT. There are a lot of people who devote their careers to understanding these tools and workflows. Most of the tools have demo versions or are free. The defacto standard in the industry is Framemaker, which is a pretty conservative bet for any project and very "middle of the road." It only works properly on Windows, so you might need to buy a dedicated box for it in some environments.
Once you have built a workflow around some tools, the job of maintaining the documentation becomes much easier. Again, I highly recommend you hire a pro to set it up, otherwise you may end up doing it all over again as you run into tool limitations and realize you failed to follow industry best practices and now have to migrate everything or customize every tool you use.
László Bíró, the journalist that invented the ballpoint pen, is a naturalised Argentine born in Hungary.
The wristwatch was invented by Alberto Santos Dumont (of "not-quite-first heavier-than-air flight" fame and "first to circle Eiffel Tower in a dirigible ballon" fame), a Brasilian.
It's better to be the foot on the boot than the face on the pavement. ~~ tkx Kadin2048