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
Given that you make both a spelling mistake and a grammatical error in the first 100 words or so of this post ("Writting tools" for a "relative complex" piece of software, I think the best tool you can use is another person, prefarably one who can write!
Professional Idiot
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.)
If you're working with or just writing plain text, the best editor I been using is Copywrite for the Mac. Besides handling files on a per project basis, the full screen mode is great with a slider to readjust the text size on the fly.
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."
+1 for not saying TASKED, when assigned is what is meant.
Like a pencil?
I read this as Manual Writing tools as in pens and pencils. A topic dear to our hearts. So what are your favorite writing tools of the manual variety? I had a zebra telescoping pen but I found it fell apart in my pocket a lot. I've switched to the Fischer space pen and I'm loving it so far.
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.
All you pompous twats that are quick to complain about his "poor writing skills" have failed to notice that the requestor is Brazilian! English is not his native tongue and the manuals that he plans to write are probably not English either.
So, having harangued the man because of your own ignorance I must ask; How is your Portuguese? I'm willing to bet that your Portuguese is no where near as good as his English.
Pesaroso, escrita == writing
Given that you make both a spelling mistake and a grammatical error in the first 100 words or so of this post ("Writting tools" for a "relative complex" piece of software, I think the best tool you can use is another person, preferably one who can write!
Professional Idiot
I've been trying to track down some graphite ink pens. Apparently these were all the rage in the
40s, but Office Depot still makes them? They sound great in theory, writes like a pen, erasable
like a pencil (and not like an erasable pen).
Were that I say, pancakes?
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.
I use DECdocument for such things. If it's good enough for the OpenVMS documentation set (quite probably the largest documentation set out there), it is good enough for me. The best part is you'll need an OpenVMS system to run it!
As before:I think XML is the best-fit for most projects & LaTeX is appropriate for those projects which already have legacy documentation or share documentation with papers submitted to journals. However, I neglected to give a shout out to ConTeXt. ConTeXt also uses the TeX backend to produce beautiful results, but is a bit easier to program in.
At the company I work at, I'd say 90-95% of our manuals consist of screenshots with arrows, and everything's broken up into the smallest possible steps. Our typical users range from "computer-ally ignorant" to "technophobic". The few users who have actually bothered to read the manuals tell us they're the best manuals they've ever read.
Being a geek, I usually don't need manuals, but on the few occasions hell had a cold front go through, I tended to gravitate toward manuals that read more like FAQs.
YMMV.
"You know you're narcissistic when you quote yourself in your sigs." -- PRoPAiN!
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
...specifically with Mindjet's MindManager software (Windows and MacOS only I'm afraid) has made all my documentation work much easier over the past few years. Add Text notes to the map nodes and you can export to HTML, MS Word (gulp...), MS PowerPoint (double gulp...) and text.
I can honestly say it has beaten my previous forays with Restructured Text, HTML, Open Office, etc. into a cocked hat.
Give it a try...
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.
Unfortunately, they seem to have become hard to find. The next time I see any I plan to make a large stockpile purchase.
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
Use your spell checker. :) :) :)
My personal favorite is an old Koh-I-Noor 0.5mm Rapidomatic Engineer's Pencil. Nothing beats the knurled Aluminum grip for multi-hour writing sessions. Unfortunately, they shallowed out the knurling some in '97 or '98, which makes it too slippery for multi-hour writing sessions. I've tried a Berol substitute, but the barrel is too heavy, round (instead of hexagonal), and I don't like the rubberized coating.
All true geeks also do work not in some cheap spiral notebook, nor some hoity-toity Moleskine, but in an "Engineer's Computation Pad", available in college bookstores everywhere. Low-eyestrain green tint, high-quality bond, and graph lines on the back that show through enough for easy diagramming, but not so much they show up in a scan or Xerox.
I know that fountain pens are a classic fine writing instrument, but they are tough to use for lefties, and involve using absorbent writing paper (to keep my left hand from smearing the ink), instead of whatever is handy. Plus, I make mistakes.
SirWired
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.
Hmm upon reading the topic I was under the impression you were interested in tools for "manually" writing something. Upon further inspection it seems you are looking for tools to write a manual.
Whats wrong with MS word or OOo?
Harun Yahya is a "thinker" that promotes all kinds of completely bogus pseudo-scientific garbage in the support of Islam.
Have a look at their main site, it's the Muslim equivalent of intelligent design.
Now an open source project that clearly supports/sponsors such nonsense is an issue to me.
That everyone is free to think what he/she wants and be as wrong as delusional as they wish is their problem, but when an organised entity that is non-political and non-religious in nature explicitly supports objectionable views, is it moral to support that entity and give credence to their views by using their products and services, be they free and open?
"Manual Writting" -- that's good.
I use LyX for input, and LaTex for the hard stuff. Seems to work out ok...
YMMV
Ratboy
Just another "Cubible(sic) Joe" 2 17 3061
He asked for "Manual," not "Automatic," writing tools. You should be recommending pencils, pens, and mechanical typewriters.
I tried to like mechanical pencils, I really did.
.05mm leads, it always seemed like I would have to constantly rotate the pencil to avoid the line thickness changing and keep it sharp. Maybe it has something to do with the way I hold my writing instruments (at an angle). Also, I never managed to find a pencil lead soft enough or dark enough to give the kind of contrast you can get from pigment-based (or even good dye-based) pen inks.
Back when I was in school and taking lots of notes (I take rather copious notes), I thought it would be nice to be able to erase things instead of just cross them out, but I could never find a mechanical pencil that wrote as easily as a pen. Even with
It sure would be nice, though, if someone could come up with an erasable pen that wasn't a crummy ballpoint. I can't think of how you would do it, maybe something like the trick "disappearing inks" that used to be sold as gags. Even if it required a solution that had to be put on like white-out, but wasn't as obvious, that would be pretty neat.
I eventually just settled on using Pilot P-700 disposable rolling ball pens, and then white-out pens to cover the occasional mistake. Not quite as good as erasing, though.
If any other pen addicts have found a pencil that they thought was a substitute for pens, I'd be interested in hearing others' experiences.
"Ladies and gentlemen, my killbot features Lotus Notes and a machine gun. It is the finest available."
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
One thing that came to my mind after some decent sleep is M4 preprocessor.
;)
I recommended LaTeX earlier, but it has one drawback in comparision to reStructuredText -- it cannot easily output different formats, basically just DVI (later convertible to PS) and PDF. rST on the other hand, while able to produce HTML, SGML, PDF, even LaTeX and other file formats, lacks any macro/language extension capabilities.
But you can process rST documents, like any other text files, with generic preprocessor like M4 to achieve that goal. Couple it with make and you have consistent, extensible documentation system without a learning curve
Robert
Bastard Operator From 193.219.28.162
"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."
*note to self* Do NOT become a programmer. Apparently being run over by a bus is one of the job hazards.
It is not too much different than reStructuredText, it gives readable ascii content, but it target producing html and... DocBook. For Docbook, there is a system of redefinable tags (I have not used them, but I've read about them in the doc).
You can find more informations at http://www.methods.co.nz/asciidoc/.
A+
Laurent.
L.Pointal
What's the scope and scale of the manual? If it's a complex piece of software, the manual is probably more than a few pages, which rules out Word. Word tends to choke on long documents.
FrameMaker is a good choice. It was designed specifically for producing large manuals. Unlike Word, it does a good job of separating content from layout, meaning you can concentrate on writing stuff instead of having to fiddle with layout issues. Its main drawback is limited support of non-Western languages. If you need to translate your documents to Thai or Arabic, FrameMaker isn't the best choice. With products like Webworks ePublisher or Robohelp, you can publish to various HTML and other online formats, including context sensitive help.
There are other packages geared towards producing large manuals. AuthorIT is one I can recommend. Unlike FrmaeMaker, it supports Unicode. It's built on top of a database, meaning you have document management facilities which come in handy if you're writing lots of related manuals, reusing text etc. It also offers export to Word, PDF and online formats.
Others I haven't worked with.
Some have recommended LaTeX. My experience with this is limited. You really need a graphical front end to flatten the learning curve. Changing the layout of your output isn't straightforward either.
I don't know how well OpenOffice handles long documents. But the way it's built to mimic Word makes me wary. Does it have a way to consistently apply styles?
From the wording of Saulo's post, I guess he's a developer. No offence, but few developers are good writers. For one thing, many developers (and engineers in general) have a hard time putting themselves in the customer's shoes. This leads to manuals that omit lots of information that's obvious to the engineer, but not to the customer. You may be better off hiring a technical writer instead.
(I write manuals for a living. I mainly use FrameMaker and AuthorIT. )
If you are thinking about writing technical manuals, I recently saw a demo of something coming out from ThirtySix Software (http://www.thirtysix.net/) which might help. It seems to give you the ability to do some structured-authoring type things (reusable text, conditional text, etc.) in Microsoft Word. Might be worth checking it out...
There are WYSIWYG xml editors out there - so you don't have to delve down into the ugly details unless you really want to -- and you can modify the online look via CSS, and use other filters to generate PDF, and other formats as needed.
It is not rocket science.
Kupu, an open source WYSIWYG XHTML editor that you can run from your web browser can be found here: http://kupu.oscom.org/
Lodragan Draoidh
The more you explain it, the more I don't understand it. - Mark Twain
How about a spell checker? :P
I wouldn't dream of writing a large document in anything other than LaTeX; the learning curve may be a bit steep but once you're up to speed you'll be amazed and thankful for the gobs of work the system will save you. Plus you can use whatever text editor you're most comfortable with; also, the format lends itself greatly to use of collaboration and revision control tools which will simplify your work even further.
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.
Is this going to be a web based manual? or something printed?
I write technical manuals that need to go to print. I've been using Adobe Indesign for my projects. It works pretty well for making prints and PDFs as well as being (somewhat) easy to use.
But it's not open source..
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
I just ordered and update for my personal, home copy of FrameMaker. It is not cheap, but it is the best text/word/document development tool I've ever used. For technical documents, especially large ones - including books, it has everything you need. It supports multiple output formats, WYSIWYG editing, and has a slick math formula tool.
Check out the free evaluation.
What I don't like about FrameMaker? Adobe dropped the Linux port, after a successfull beta test, due to lack of interest... sigh...
YARIFTRW (Yet Another Reason I'm Force To Run Windows)
For every problem there is a solution that is simple, obvious and wrong.
used docbook for a project. Generates HTML and pdf from same source.
Can have multiple files and include them in the main file, saving writing same things multiple times.
There is a learning curve, but I thought it was worth it.
We use a system from AuthorIt in NZ. It provides support for an object document model with multiple output templates.
You could try Open Source Daisy for your manuals. http://www.daisycms.org/
http://docutils.sourceforge.net/docs/howto/rst-dir ectives.html The directives aren't doing it for you?
-I like my women like I like my tea: green-
i prefer an 1827 feather pen with ink made from natural plants [talk about manual]