POT: (Possibly Off-Topic?) Software to create a User Manual

I use Word, and then CutePDF. We use SolidWorks or Autocad or Visio to do most diagrams, and lots of photographs. The manuals look fine.

98% of the work in making a manual is creating correct content. Word adds very little overhead... unless you waste a lot to time playing with styles and macros and things.

Customers mostly care about content, not cosmetics. A good looking manual is a sales tool, but Word is good enough.

--

John Larkin         Highland Technology, Inc 

jlarkin att highlandtechnology dott com 
http://www.highlandtechnology.com

I've been using FrameMaker for more than a decade (two?) for all my writing needs (even business correspondence). Largest documents are in the ~1K pages range and easily manageable (I started using FM on a 386 -- for a 500pp document!)

Prior to that, I used Ventura Publisher which, in many ways, is (was) an even better product. But, Corel has butchered it, IMO. There were many things that I could do "automatically" in VP that FM can't (and MS couldn't even ATTEMPT!)

The big appeal in FM is the lack of surprise -- you can pretty much count on it doing what you would expect it to do (unlike, e.g., Word that has subtle dependencies in it's styles/tags).

[This was even more apparent in VP!]

It also supports structured documents, SGML, etc.

I've probably prepared about 5,000 pp of "professional documentation" using it (20pp - 1000pp at a time). Recently had a problem importing a CAD drawing but suspect it was the fault of the tool that created the drawing in the first place ("not-quite-AutoCAD-compatible")

Word is a dog. You will end up with bloated documents that take a long time to load, edit, etc. And, will probably NOT be supported in the next version of Word!

FM would have you producing output almost immediately. Creating your own character, paragraph and document styles/tags takes a while -- usually because you need to think about what you really want to use the tags/styles for.

E.g., I don't have an "italics" style. But, I do have an "emphasis" style and a "foreign language" style -- both of which appear, visually, as italics. (The difference is, one is USED to indicate emphasis in my prose while the other is used to tag foreign language words and abbreviations, "etc.")

In the same sense, I have styles for things like "program code", "document title", "figure caption", etc. So, I can change how I present each of these "types of information" -- as well as extract those pieces of information from the document algorithmically.

Keep in mind any others that may have to come along after you (or alongside) in that effort. This, IME, is what drives people to adopt dogs like MSWord ("Oh, all the secretaries use it!" Yeah, and when they botch your document, YOU can sort it out, later).

Also, look at some of the ancillary operations that you will inevitably need to perform (ToC, index, list of figures, list of tables, etc.) and how readily this is supported. Often, these are more important than the prose -- if a reader can't quickly find what he needs, then all the words and pretty formatting in the world won't help!

First, anything you do will need careful setup and a lot of work to produce a really polished, professional, and unique work. You can't get out of that. There's just a lot of production involved in writing a book, even if it never gets published in any way other than as a pdf.

LyX is my current favorite, but I'm not sure how your learning curve will go. It's basically a front end for LaTeX, which is probably the best method for producing book-length (or library-length) works. You'll probably end up having a separate document for each chapter, then some sort of a master document to render the whole book when you're done.

Word can do book-length works, but if it still suffers the same limitations it did the last time I used it, you don't want to have the whole thing open all at the same time, except on special occasions (think computer crashes). Instead, use a Master Document to hold the chapters, then write each chapter as a separate .doc file.

LibreOffice (or OpenOffice) has similar limitations to Word, and the same solution -- use a master document.

--

Tim Wescott 
Wescott Design Services 
http://www.wescottdesign.com

+1

Your best bet is to author the thing as a Word document with no added styles or anything -- make sure that the author understands that each different "look" should be done with a different style, and that should be held to a minimum. (You essentially want to do the LaTeX thing here -- the style of a paragraph is a statement of the author's intent, like "heading

1", "heading 2", "bulleted list", etc. The actual treatment of those various styles is a statement of the production person's desire, like big bold text, gothic typeface, whatever).

Then add in all the gew-gaws at once, at the end, by experimenting with styles and whatnot. If you take my suggestion of using a master document with chapter documents, then you can do all the messing around with the look in the master document, and leave the chapter documents as plain-jane.

--

Tim Wescott 
Wescott Design Services 
http://www.wescottdesign.com

I turn off practically every automatic feature of Word, and don't use styles or macros. I use it like a text editor that lets me include font sizes and pictures. I hate it when I inherit a Word doc that's all stylized and gimmicked, so that simple things don't work.

Too often, people want to play with the tools, instead of doing the work.

--

John Larkin         Highland Technology, Inc 
picosecond timing   precision measurement  

jlarkin att highlandtechnology dott com 
http://www.highlandtechnology.com

How's this fit with your expectations?

I suspect the learning curve won't be a very good fit though...

Tim

-- Seven Transistor Labs Electrical Engineering Consultation Website:

Anyone know (or have a favorite) software tool to create a User's Manual? This manual will support a moderately complex software tool that is 4 years in the making. I'm expecting the manual will be on the order of 150 pages or so. (That's a guess. My point I'm trying to make is this is not going end up being a eight-sheet half-page booklet!)

I can do it in Word, of course, and I do have some decent templates I could probably adapt but I'm pretty sure Word is not the best way to go.

I saw this online (cursory Google Search).

I like that it can output to various formats, including mobile, etc... That said, I don't think mobile format is essential for the current project, but it's a "nice-to-have" thing in the box for future needs (yet unknown, of course). The Flare pricing is $999 for a perpetual license, though. I'm going to request the demo.

So to recap: My question is does anyone know or have experience with tools to create professional looking User Manuals? Ease of use is important, but a learning curve is acceptable - unless the curve is very, very steep - as I imagine some of these tools might be.

Thanks everyone!!

Of preference, I would use LaTeX - it's solid software that will help you get a good, consistent layout with top-quality typography. It is particularly useful if you have any maths involved, and produces much nicer tables with much less effort than any gui tool I have used. Another key advantage is that the file is plain text - that means it works well with version control software for tracking changes and versions of the documents. It also means that it is easy to build it up in parts (perhaps there will be different people working on different sections), or to include things like source code (with LaTeX packages to automatically format it) or externally generated data. The ability to make macros and new commands lets you automate common sections or layouts, and helps keep everything consistent. Once the document is generated as a pdf, you'll find all your cross-references really work, and your table of contents is generated properly.

It takes a bit of time to learn LaTeX - it is not a gui wordprocessor. But this is a big document - you can afford to spend a little time on the tools to save time overall, and generate far better quality. Once you have used LaTeX for a while, you'll cry every time someone asks you to use Word.

Tim mentioned LyX - it's a sort of gui front-end to LaTeX. Personally, I prefer to use a good LaTeX editor (there are several, depending on the platform you use - since I use eclipse for a lot of my programming, I find it convenient for LaTeX too). I have only tried it a little, but LyX always struck me as dumbing down LaTeX a bit - it makes it easier to do easy things, but harder to do harder things.

If you do have to use a word processor, choose LibreOffice over Word. It is far better for the job, for three main reasons. One is that it makes it easier to use styles, and harder to use manual formatting - nothing will spoil your work faster than using manual formatting instead of styles. Secondly, you can work reliably with large documents - with Word, you take a big risk of corruption if you go over around 20 pages (depending on the mix of text and pictures). Thirdly, it can generate pdf documents directly. If you have used styles properly, and proper bookmarks and links, then these carry through to the generated pdf. The result is a decent pdf (though not nearly the quality that you get from pdfLaTeX) that is easy to navigate - far better than the flat "printout" pdf you get with Word and a pdf printer, and far more efficient, faster, and easier to make than using Adobe's monstrosities.

Adobe Indesign is a great tool for writing manuals and datasheets, especially if you care about the way the result looks.

David just said everything I tried to say, only better.

Clearly I don't quite agree with him on using naked LaTeX vs. Lyx (it's easy enough to dive down a layer and just type in LaTeX code for the "hard stuff" in Lyx, where with LaTeX I find that I have to keep the manual by my elbow at all times), but aside from that, +1 to everything he says here.

If I didn't have Lyx, I'd be doing my documents in LaTeX in preference to OpenOffice or (blech) Word.

--

Tim Wescott 
Wescott Design Services 
http://www.wescottdesign.com

Which is why I use LaTeX. ;)

Cheers

Phil Hobbs

--
Dr Philip C D Hobbs 
Principal Consultant 
ElectroOptical Innovations LLC 
Optics, Electro-optics, Photonics, Analog Electronics 

160 North State Road #203 
Briarcliff Manor NY 10510 

hobbs at electrooptical dot net 
http://electrooptical.net

For most of the documents I write at work, I use LibreOffice for compatibility with other people who don't want to learn LaTeX, but occasionally I "break the rules" and use LaTeX. I hope to convince others to use it sooner or later.

Maybe my bias against LyX is just that I like to separate my editor, and to build things from the command line (with make). LaTeX with a makefile (handling things like generation of graphics with graphviz or imagemagick) suits me just like I prefer makefiles to some sort of "project manager" for my C code.

One thing I have heard about LyX, but don't know for sure, is that it is not always an easy matter to use standard LaTeX packages in LyX documents. I often use my own class (modified from article), and I make a lot of use of \newcommand to help keep my documents consistent. As far as I know, LyX doesn't deal well with such things, showing them as grey boxes which spoil the wysiwym appearance.

Here's another completely different idea - use doxygen. Although it is typically used to generate documentation from source code (C, C++, plus others), you can write the input as plain text files written with a simple markup language. Doxygen can turn that into a set of HTML files or a pdf document (using LaTeX), or even Windows chm format (if that helps for the manual).

That's the usual problem with LaTeX GUIs, IME. I tried Scientific Word back in the day, but it required its own macro set, which conflicted with the ones supplied by the publisher.

I grew up writing markup in a text editor (SCRIPT/VM and Bookmaster on XEDIT), so it really isn't that different writing LaTeX.

If the publishers would still accept it, I'd still be using WordPerfect

5.1+ for DOS, which AFAICT is just about perfect for everything I need a docs package to do.

Cheers

Phil Hobbs

--
Dr Philip C D Hobbs 
Principal Consultant 
ElectroOptical Innovations LLC 
Optics, Electro-optics, Photonics, Analog Electronics 

160 North State Road #203 
Briarcliff Manor NY 10510 

hobbs at electrooptical dot net 
http://electrooptical.net

Frame Maker.

Thanks everyone who has responded thus far.

An important datapoint I left out of my original post is that, at least ini tially, the document is primarily to support the sale of the software to a large already interested company (hopefully for big bucks). So, it does ha ve to look polished and professional - in addition to having the right cont ent (as was mentioned above).

The software is kick-ass (that's a technical term). It would be a shame to see the asking price plummet because the associated User Manual looks like it was written on the back of a napkin!

It will actually sell without a User Manual (I think?), but for the dollars invovled we really do owe them something approaching a professional look a nd feel. Human perception of quality is a funny thing. (This IP sale will be driven by the company's engineers, so the User Manual may be more of a formality anyway. We fully expect they are going to modify the software on ce they acquire it, or us, anyway. The Buyer has their own font. Enough s aid?)

Frankly, I would perfer to farm this out, but there'd be too much back and forth.

I've pretty much decided against Word - certainly the 2013 version which I' m quite clumbsy with. In a real pinch, I suppose I could use the XP machin e and Word-97, with which I am far more proficient regarding the mechanics of desktop publishing.

That said, I will definitely look into LaTex (and variants), and Frame Make r, and report anything I may stumble upon in the process that looks equally promising.

Thanks again everyone.

Manual?

years in the making. I'm expecting the manual will be on the order of

150 pages or so. (That's a guess. My point I'm trying to make is this is not going end up being a eight-sheet half-page booklet!)

could probably adapt but I'm pretty sure Word is not the best way to go.

project, but it's a "nice-to-have" thing in the box for future needs (yet unknown, of course).

to request the demo.

professional looking User Manuals? Ease of use is important, but a learning curve is acceptable - unless the curve is very, very steep - as I imagine some of these tools might be.

MS word is pretty good. For really professional results you need something like the once famous ventura publisher. I have done a 53 page user manual in WordPerfect but it was only ok. Oh and that was about 24 years ago.

?-)

The other thing to think about as you are writing the paper manual is to make the online help system for the product if possible derivable from the manual source itself. Both will need to use pretty similar screenshots and it makes good sense to maintain one common source.

Word makes a pigs ear of export to HTML but there are simplifiers available that can remove the abundant dross it adds to content.

If it is for serious volume product then going to a design house that specialises in software manuals and giving them your draft plaintext is

*the* way to go. They will ask you the questions that mean that the manual actually describes what a novice really wants to know about the software as opposed to highlighting the parts you are most proud of. They have to understand the software from a users perspective (you will see it from a developers perspective and are too close to it).

The Microsoft Help system for Word would define HELP as:

"he" the masculine pronoun "LP" obsolete form of recorded music on black vinyl disk

Word2002/3 was the peak in functionality. But if you are only going to originate the plaintext then it hardly matters. You give your manual writer a copy of the software and your written notes and they decide which screen grabs to insert where to explain the key stages.

My main dislike of Word is WYSINWYG if the printer driver changes. (and sometimes even dependent on wind direction)

Do think about the online help system too!

--
Regards, 
Martin Brown

Have a look at Pandoc and consider writing in Markdown. You can then produce LaTeX, EPUB etc. Highly recommended.