Slashdot is powered by your submissions, so send in your scoop

 


Forgot your password?
Close
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? More

Manual Writing Tools?

Comments Filter:

  • Lawyers (Score:5, Funny)

    by albalbo ( 33890 ) on Monday June 19, 2006 @05:57PM (#15564855) Homepage
    I get my lawyers to do it; they're my writting machines.

    • Re:Lawyers (Score:1, Funny)

      by Anonymous Coward
      I was expecting a joke about habeas corpus, but I suppose that would be rather anachronistic.

  • 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?

    • Re:Just a suggestion... (Score:1, Funny)

      by Anonymous Coward
      No, no, you get it all wrong! You are supposed to suggest writing everything in DocBook, using Emacs or Vim. Using efficient plain-text is so 70s. Modern people use Java-based XML-processing-frameworks that use 156MB JVM-space to process a 500 byte README.

      • You're both wrong. (Score:3, Funny)

        by Anonymous Coward

        He asked for "Manual," not "Automatic," writing tools. You should be recommending pencils, pens, and mechanical typewriters.

    • If I were to write or rewrite a user manual, I'd find some way to do it in LaTeX, since that allows all sorts of template and macro forms, and can be output as PDF, HTML, and other things, and can be edited in a plain text editor. There's also lots of packages out there already (see CTAN) that might be helpful by having templates and such that might be close to what you need.

      But, I'm not sure what output forms you need... SGML? manpages?
      (Is there a link on the reply-to-a-comment page that takes me to the m

  • Your #1 site for quality editorial work! (Score:3, Funny)

    by bunions ( 970377 ) on Monday June 19, 2006 @05:58PM (#15564869)
    writting!

    in other news, sarcasm is the lowest form of humor.

  • "Manual" you say? (Score:5, Interesting)

    by Fallingcow ( 213461 ) on Monday June 19, 2006 @05:59PM (#15564870) Homepage
    I like ballpoint pens.

    (thought I was going to be getting a pen discussion until I read past the headline)

    • Me, too. I was so disappointed. I would have enjoyed a discussion of the wide variety of freehand hard-copy editng implements. But I suppose that's cause I'm sick in the head. Then again, that there exists a sufficient number of people interested in the actual topic of the article does not speak well for general sanity, either.

    • Re:"Manual" you say? (Score:4, Interesting)

      by GospelHead821 ( 466923 ) on Monday June 19, 2006 @06:50PM (#15565191)
      That was my first thought as well. A while back, I got into several lengthy discussions about handwriting implements. I am quite fond of the Pilot G2 pen. The ink smears a little bit, but the colours are vibrant, the cartridges are easy to obtain, and they are also used in the Dr. Grip series of pens, which are very comfortable and stylish. They're also the only gel ink cartridge I've ever used that doesn't dry up in the tip and clog the pen if you don't use it for a few weeks.

      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.
    • "(thought I was going to be getting a pen discussion until I read past the headline) (Score:3, Interesting):

      Erm... did somebody with a mod point just admit to not reading past the headline? Heh.
    • I like ballpoint pens.

      ...which were invented by a Brazilian, iirc. Biro?

      • 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.
    • I bought my favourite pen (for writing) in the UK. It's a cartridge pen (you know, the type with an actual nib) that cost UKP 1.99 from WH Smith. It's astonishing. My fanciest pen is a beautiful Edgar Allen Poe Mont Blanc that cost about $1000. It's beautiful to look at, but my $4 pen from WH Smith writes better.

      I've never got on well with ballpoint pens.

    • Re:"Manual" you say? (Score:4, Funny)

      by Anonymous Coward on Monday June 19, 2006 @08:07PM (#15565606)
      I'll take 'penis mightier' for 500
    • I actually prefer pencils (the mechanical kind). That along with a good vinyl erase is the best writing instrument. You can correct your mistakes, and you don't ever have to sharpen the pencil. And they maintain a relatively consistent sharpness.
      • I tried to like mechanical pencils, I really did.

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

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

          by CastrTroy ( 595695 ) on Tuesday June 20, 2006 @08:32AM (#15568132)
          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.
          • Mitsubishi makes (and sels in japan and in the US through importers) a 0.18 pen. Its great for fine writing, but I find its rate of flow too low for normal size writing.

                                --Michael

  • Manual Writting Tools? (Score:5, Funny)

    by ozbird ( 127571 ) on Monday June 19, 2006 @06:00PM (#15564883)
    If you find a good spellchecker, let the Slashdot editors know... (Manual Writing Tools.)

  • "Manual Writting Tool"? (Score:3, Funny)

    by ctid ( 449118 ) on Monday June 19, 2006 @06:05PM (#15564911) Homepage
    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.

  • A spelling checker, for one (Score:3, Interesting)

    by RobertB-DC ( 622190 ) * on Monday June 19, 2006 @06:06PM (#15564919) Homepage Journal
    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 [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.
    • Easy to read or not, you've got to give the guy his due for actually knowing how to use a semi-colon properly; it's a quickly fading skill.

      • Re:A spelling checker, for one (Score:1, Insightful)

        by Anonymous Coward
        I am guessing that the guy who wrote the coherent lead probably did not write the illiterate headline.

    • 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

    • I would agree with the need to bear your audience in mind.

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

      Parent touches on a good point. No offense meant to original poster; but, if this post is any judge of your writing it might be wise to consider hiring a professional technical writer... at least an editor. No offense meant, but your english could use a little polish.

      It's a significant investment to rewr

  • 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.
    • Personally, I tend to like just a regular old wiki for documentation – for example, most of the documentation for Ultima Linux is on a MediaWiki site [ultimalinux.com]. Although this might not be the best way if you need printed documentation, because of the fundamental differences between a Web site and a wiki. Of course, if the primary method of providing documentation is going to be printed, I'd say learn LaTeX – it's really not very hard at all, and it tends to be very good for technical documentation becau

      • Wikis, LaTeX (Score:3, Informative)

        by Noksagt ( 69097 )
        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
      • However, DocBook has the capability to write the documentation once and, via xslt, give you a nice website, print form and help file for an application.
      • 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. [contextgarden.net]

      • It sort of depends on your perspective. If I was a programmer with an extant, well-involved userbase, and I didn't have a lot of time or resources for documentation, I'd probably just throw up a wiki and edit it when people had questions. This would work especially well if I weren't highly concerned with the quality and consistency of the docs.

        With that last part I'm not saying that unprofessional material is a necessary consequence of a wiki, just that if I had to hand something off to my boss or a print

  • How about Word? (Score:2, Insightful)

    by JeffHunt ( 129508 )
    Or OpenOffice? Word processors are good at processing, uhm, words... you know.

    • 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.
      • I use LaTeX for almost everything these days

        You must have a lot of experience in it. I have a question for you. How do you turn on automatic word wrapping in a tabular block?

      • I can't stand using finicky, annoying WYSIWYG word processors anymore. LaTeX is simply a better way.

        LaTeX may be better than Word, but better than any WYSIWYG word processor? I find that hard to believe. Try using a real WYSIWYG application like FrameMaker. All the consistency of LaTeX, plus a GUI that actually helps you instead of getting in the way.
        • Comment removed based on user account deletion
          • FrameMaker has its limtations, sure, I never said it was perfect. Language support is limited to Western, East European and CJK. If you need others, use another tool.
            On the website for LyX, I find this comment: " Support for writing documents in most European languages" - most? So LyX (or LaTeX) has language limitations as well?

            Fortunately, many product manuals can do without Sanskrit and consonant charts.
            As for the 'only one language' dig: wrong. We've produced loads of multilanguage manuals.

            LaTeX has its
            • Comment removed based on user account deletion
              • Somehow I doubt that the ligatures and hyphenation were correct, however.

                For all languages supported by Frame, the hyphenation was definitely correct. Ligatures we usually don't bother with. We produce manuals, not novels or typesetting showcases.
                If the language isn't supported by Frame, we don't use Frame to produce the book. After 10 years of producing manuals, I can count the number of times that has happened on one hand.

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

  • If you're working with or just writing plain text, the best editor I been using is Copywrite [bartastechnologies.com] 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 (Score:4, Insightful)

    by calumtdalek ( 983493 ) on Monday June 19, 2006 @06:23PM (#15565026) Homepage
    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 [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?

  • Writting - not what you think (Score:5, Informative)

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

  • +1 for not saying TASKED, when assigned is what is meant.
  • 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'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).
    • 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
  • 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!

  • 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
    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
    • If you're going to use FrameMaker, there are loads of output tools available. RoboHelp Frame is easy to use, but not the most flexible in terms of formatting the output. Webworks ePublisher is very flexible, but rather arcane if you go beyond the provided templates.

      If you want/need to provide a Word file, use Mif2Go.
  • 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.

    YMM

  • Digital had a neat pattern (Score:3, Insightful)

    by Nefarious Wheel ( 628136 ) on Monday June 19, 2006 @07:32PM (#15565442) Journal
    Digital Equipment Corp was known for their well laid out, informative and easy to use VAX/VMS manuals (cue old "three rooms of heaven" jokes). They were highly automated. They used Edit/TPU templates for coding that enforced carefully structured comments in program code, followed by a program that stripped the comments from programs written that way and structured them into a book, with appropriate fonts and styles. What followed was simply editing the output of that program and printing it, a much easier job than writing the entire document from scratch.

    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.

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

    • I, too, am a big fan of mind mapping and am familiar with different mind mapping applications although not the one that you reference. I find mind mapping to be great for organizing ideas. It is sort of an outline on steroids. However, I don't see how mind mapping is very helpful in presenting rectilinear information. How do you use this product to present a table of information?

      • The application I mentioned (MindManager [http://www.mindjet.com/]) allows you to add RTF style text notes to each node within a special notes box (which is not standard mind mapping); when you export to MS Word these notes appear in the Word document as body text (and the map's nodes / branches as headings). The notes can acommodate images and tables and the usual RTF formatting.
        I started with Freemind but that didn't have notes and didn't export to MS Word very well and that was the main feature I was loo
  • 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 [wikipedia.org] system like AuthorIT [wikipedia.org]. 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

  • 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
    • You let the developers touch the source files for your manuals? In my experience, that usually leads to things breaking, not to mention that the writer will have to review all of the developers' changes to filter out the Engrish and programmer-speak. Better to let the code monkeys provide their comment in a different format. Developers != good writers, in most cases.
      PDF is ideal for reviewing: the reviewer can add comments to the PDF, and the writer can easily integrate multiple comment sets into a single P
      • Oh, the beauty of Revision Control Systems ;)

        At the time I was running docs repo we used CVS. There are multitude of graphical clients for all platforms. People responsible for documentation's correctness just had to review recent changes (via graphical tools comparing versions side-by-side, with changes highlited), correct Engrish and check in new version.

        Saves lots of time.

        Robert

  • We need more info, but here you go.... (Score:4, Insightful)

    by ProppaT ( 557551 ) on Monday June 19, 2006 @09:10PM (#15565847) Homepage
    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.

  • Lyx Editor and LaTeX (Score:3, Interesting)

    by imagineit ( 618047 ) on Monday June 19, 2006 @09:46PM (#15565994)
    I was also searching for a better way to create technical documenation and stumbled upon Lyx http://www.lyx.org/ [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.
  • "Manual Writting" -- that's good.

    I use LyX for input, and LaTex for the hard stuff. Seems to work out ok...

    YMMV

    Ratboy
  • 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 [wikipedia.org] to achiev

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

      by crush ( 19364 )
      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]

      • 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

        Yeah, sure... First, I did write, that you can generate PS and PDF from LaTeX, you've just cut it. And second: go, convert to HTML, RTF, WordPerfect any decent LaTeX document with custom macros, styles etc.

        You see, I do use LaTeX daily, did manage huge documentation re

  • 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 tr
  • 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/ [oscom.org]
  • 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.

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

      I like Latex and use it for some projects, but the language itself is very cludgy and dated. You have to use hacks to insert graphics or even color text. Now these hacks are very well known and explained, but it is still a huge pain. It also is problematic if your project ever becomes large

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

  • I just ordered and update for my personal, home copy of FrameMaker [adobe.com]. 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 (

Slashdot Top Deals

Solutions are obvious if one only has the optical power to observe them over the horizon. -- K.A. Arsdall

Close