Forgot your password?
typodupeerror

Manual Writing Tools? 139

Posted by Cliff
from the from-code-to-printed-man-pages dept.
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?"
This discussion has been archived. No new comments can be posted.

Manual Writing Tools?

Comments Filter:
  • Just a suggestion... (Score:3, Informative)

    by DrMorris (156226) on Monday June 19, 2006 @05:58PM (#15564868)
    ... what about sticking with reST and using m4 or other macro package to do repeated tasks?
  • XML! (Score:3, Informative)

    by Noksagt (69097) on Monday June 19, 2006 @06:16PM (#15564991) Homepage
    XML formats aren't very friendly to code or edit in, either
    You're doing it wrong. There are a number of excellent XML or general text editors that do the job. There are even online collaboration tools, such as DocBookWiki [sourceforge.net]. Most importantly, it is easy to get programmatically-generated documentation in XML & also easy to reformat XML into your destination formats.
  • some ideas... (Score:5, Informative)

    by tjr (908724) on Monday June 19, 2006 @06:19PM (#15565008) Homepage
    In my previous job, I wrote a lot of documentation using a program called Help and Manual [helpandmanual.com]. I can't say that I thought it was wonderful, but it was functional, especially if you need to make Windows Help files.

    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.)

  • by Qbertino (265505) on Monday June 19, 2006 @06:28PM (#15565048)
    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 [blender.org] 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?
  • Re:LaTeX (Score:5, Informative)

    by bunbuntheminilop (935594) on Monday June 19, 2006 @06:28PM (#15565056)
    ++

    Lyx is a good frontend for Latex too. Its no subsitute for writing it by hand, but then again, there is no subsitute for Latex.

  • by Wonko42 (29194) <ryan+slashdot&wonko,com> on Monday June 19, 2006 @06:29PM (#15565061) Homepage

    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.

    The use of "existent" in the above sentence is awkward, and the parentheses are unnecessary and confusing, but the semicolon is used properly. It would have been acceptable (and probably less confusing) to break the sentence into two sentences, but that doesn't mean the semicolon was misused.

  • by Anonymous Coward on Monday June 19, 2006 @06:33PM (#15565071)
    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."

  • Re:How about Word? (Score:5, Informative)

    by Penguin Programmer (241752) on Monday June 19, 2006 @06:49PM (#15565178) Homepage
    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.
  • Wikis, LaTeX (Score:3, Informative)

    by Noksagt (69097) on Monday June 19, 2006 @06:51PM (#15565203) Homepage
    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.
  • Some ideas (Score:4, Informative)

    by Phat_Tony (661117) on Monday June 19, 2006 @07:14PM (#15565332)
    I don't know what all the features are that you're looking for, and I don't know if you work on a Mac, or which of the following programs have PC equivalents, but here are some programs which I think are scriptable, template-using, auto-formatting word-processors aimed at managing, editing, and producing books, manuals, and other similar projects:

    LaTeX [lyx.org] (I'm pretty sure this is available for Linux & Windows too)
    Mellel [mellel.com], which has some very good reviews
    Manuscript [www.iol.ie]
    Which may not be as full-featured.

  • Possible Tools (Score:2, Informative)

    by Anonymous Coward on Monday June 19, 2006 @07:14PM (#15565333)
    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.
  • by DragonWriter (970822) on Monday June 19, 2006 @07:14PM (#15565338)
    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.
    While the sentence you quoted may have been confusing, the semicolon was properly used, and shouldn't be blamed for any confusion.
  • I hope you realized that this guy is from Brazil. Maybe his first language isn't English and he is writing the documentation in Portuguese?
  • LaTeX? (Score:5, Informative)

    by Gadzinka (256729) <rrw@hell.pl> on Monday June 19, 2006 @08:03PM (#15565586) Journal
    If you used reStructuredText and liked it, but found it lacking in some features, why don't you try LaTeX [wikipedia.org]? 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
  • by sgarg (197658) <s.garg@nosPaM.computer.org> on Tuesday June 20, 2006 @01:08AM (#15566794)
    Just started out with Vex http://vex.sourceforge.net/ [sourceforge.net]. It looks to be a pretty neat XML editor, based on Eclipse, with the DocBook DTD http://www.docbook.org/ [docbook.org] built in.

    I have been a longtime user of LaTeX http://www.latex-project.org/ [latex-project.org] and have found TeXnicCentre http://www.toolscenter.org/ [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/ [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 ...

  • Re:Pencils and Pens (Score:4, Informative)

    by CastrTroy (595695) on Tuesday June 20, 2006 @08:32AM (#15568132) Homepage
    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.
  • Professional Help (Score:3, Informative)

    by 99BottlesOfBeerInMyF (813746) on Tuesday June 20, 2006 @11:06AM (#15569366)

    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.

  • Re:M4 + anything (Score:3, Informative)

    by crush (19364) on Tuesday June 20, 2006 @11:52AM (#15569767)
    LaTeX [...] has one drawback in comparision to reStructuredText -- it cannot easily output different formats, basically just DVI
    LaTeX can be converted to HTML, PDF, PS, ASCII, RTF and there are also a variety of converters for WordPerfect etc [tug.org]
  • by hummassa (157160) on Tuesday June 20, 2006 @11:59AM (#15569837) Homepage Journal
    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.
  • Re:How about Word? (Score:1, Informative)

    by Anonymous Coward on Tuesday June 20, 2006 @12:55PM (#15570341)
    Dude I downloaded LaTeX for Windows last Wednesday and I'm hooked. It used to take me 30 minutes to do a single equation in Word's shitty editor; now I spew them out from my keyboard in seconds. LaTeX is absolutely fantastic - God's gift to anyone who needs to write documents with mathematics in them. And it just comes out looking like every textbook and paper that you've ever read - which actually adds a sheen of authenticity to your mistake-ridden work ;)

    I love LaTeX. I just wanted to say that.

    BTW if you can write HTML, you can write in LaTeX. It's not hard to learn at all.

    Here is where I started: http://www.math.vanderbilt.edu/~schectex/wincd/int ro_to_tex.htm [vanderbilt.edu]

    Honestly I was writing complex vector equations down within a few hours, and most of that was download time.

    Get the PDF "The Not So Short Guide to LaTex 2e" from here (linked on the above page):

    ftp://cam.ctan.org/tex-archive/info/lshort/english /lshort.pdf [ctan.org]

    Skim through that while the packages download and you're golden.

"I've seen the forgeries I've sent out." -- John F. Haugh II (jfh@rpp386.Dallas.TX.US), about forging net news articles

Working...