Software for Installation/Operation/Maintenance manuals 9

[geesamand]

I hope I've found an appropriate forum for this question.

We make basic IO&M manuals in Microsoft Word. These range from 1 to 100 pages, and given the complexity of Word's formatting capability and the size of the documents, can be unproductive and extremely frustrating. Our users are not desktop publishers either - I would describe this as a graphics-laden word processing application. The final output is a PDF file or print copy of the manual (we're not into those fancy hyperlinked digital manuals I've seen in some industries). A feature for handling multiple languages would be nice but not a priority. We need to keep the editing of these documents easy enough that multiple users in the company can be competent to work with these documents.

Instead of Word, here are some options:
- WordPerfect (same capabilities of Word, just 'better')
- Adobe Framemaker (more desktop publishing in nature, more training required)
- Madcap MadPac (seem geared directly toward technical manuals)
- Others?

I welcome your input, as we are not a big organization and we need this to work well.

 

[MintJulep]

Open Office.

 

[micalbrch]

Word is the best. We used to work with Framemaker in the past, but that requires more training as you already wrote. Nowadays all our manuals are made in Microsoft Word.

 

[geesamand]

How you do manage the formatting nightmares? Most of the formatting in our documents is inconsistent and gets corrupted. There are numerous workarounds in the formatting.

I'm pretty computer savvy and I've read some references that try to explain the Word formatting style and the complexity is simply bewildering. I'm halfway motivated to find another software simply out of spite because I'm offended that Microsoft would believe the Word formatting structure is what the world should conform to.

David

 

[MintJulep]

Like most tools, if you take the time to learn how to use it, and use it correctly, Word works well.

I've done stuff far larger and more complicated than a 100 page manual.

 

[BrianE22]

Quark or Adobe's InDesign.

 

[KENAT]

I've never known a serious technical publisher that liked Word, for the reasons you state.

We use framemaker I believe, or did until we went to the fancy html semi imbedded docs or whatever we have now.

Posting guidelines faq731-376

http://eng-tips.com/market.cfm?

(probably not aimed specifically at you)
What is Engineering anyway: faq1088-1484​

 

[Sparweb]

Going out on a limb here, but how about AutoCAD (or whatever CAD software you already use)?

Don't dismiss it out of turn: If you only need annotated graphics, then what is a CAD file after all?

Over the years I've moved back and forth on the subject. I produce documents on a pretty regular basis, and AutoCAD "almost" is convenient enough to use for this purpose, in my environment. Maybe it could be a bit more convenient for someone else. The current versions can be configured with templates to prepare numerous page layouts in advance; this can be done rather automatically. From the fundamental "model" space you can arrange the drawings and text there, within a series of border spaces that fit each of the page layouts. From there you use the "publish" command instead of "plot", and all of the pages get plotted together into one DWF output file, or sent to the printer as one batch. This DWF can be converted into a PDF in one step, too.

A lot of my documents lose some crispness when I swap graphics/drawings out of CAD and into Word. I can save that step by abandoning Word for some documents. From a revision control point of view, if ALL of the drawings and text are in ONE file, in this case the CAD file, then suddenly there is one tracked document per revision, not umpteen. YAY! Things you find in Word like headers and footers? In AutoCAD they can be attribute blocks. The ATA chapter and section numbers? Separate fields and change them at will.

Now there are some folks who can't even change the font style from TXT to SIMPLEX or something else nicer, but engineers do tend to get along with CAD jockeys.


STF

 

[Oldhydroman]

We used to produce a load of manuals and found Word difficult when handling a lot of graphics. The workaround for us was to use PowerPoint. It handles the pictures with ease and the text is carried in "text boxes" which you can place whereever you want on the page.

DOL

 

[MadMango]

We use InDesign as well.

"Art without engineering is dreaming; Engineering without art is calculating."

Have you read faq731-376 to make the best use of these Forums?

 

[Eltron]

Take a look at 3DVIA Composer. It is pretty powerful software that is fully CAD integrated for technical publications.

Dan

http://www.eltronresearch.com

Dan's Blog

 

[MintJulep]

If the complexity of Word is a problem for you then you most certainly do not want to tackle Adobe InDesign or whatever they call it this week.

 

[SnTMan]

geesamand, I do pretty much what you describe, a Word doc with a few figures and a table or two. Word drives me crazy what with the formats jumping around and changing all the time. The worst, to me, is trying to dump in a picture, I never know where it will land or how it will be formatted. Admittedly I am not well trained in Word. There must be something simpler to use, but Word is what I am stuck with.

Regards,

Mike

 

[drawoh]

geesamand,

Word, and the very similar Open (Libre) Office actually are very powerful, and the overwhelming probability is that you don't know how they work. WordPerfect works the way you probably think Word does. This makes it more user friendly.

In Word, pull up and study the Styles and Formatting menu. In Word, you should not format text as you go. You should have a set of predefined formats which you apply to your text. Then, you can make style and formatting decisions, and quickly apply these to the whole document. You do not want to go through a hundred page document, changing the level two headers to 16pt Comic Sans, or any other font, for exmaple.

--
JHG

 

[KENAT]

For internal assembly work instructions we sometimes use our CAD system. We actually have a template for this separate from regular drawings. However, for serious customer facing docs it's a bit limited. Though for the kind of instructions you get in flat pack furniture it may well be adequate.

Posting guidelines faq731-376

http://eng-tips.com/market.cfm?

(probably not aimed specifically at you)
What is Engineering anyway: faq1088-1484​

 

[MiketheEngineer]

I have used Word for many such projects. Once you figure it out (Use the HELP funtion) - it should work just fine.

There are also "HELP" type software program that you use to make manuals and "HELP" sections for proprietary software. Best thing they do is allow indexing, table of content, etc

BUT again - you must learn how to use them. Google "Help Software"

 

[dgallup]

http://www.ptc.com/product/arbortext/

----------------------------------------

The Help for this program was created in Windows Help format, which depends on a feature that isn't included in this version of Windows.

 

[geesamand]

I think our document editors (remember: this task is nobody's full-time job) are in the boat SnTMan described. The practical thing to do, as I see it, is to find some best practices and see if that cleans up the problems. We can handle graphics ok, it's the uncontrollable formatting that makes life difficult for us. It seems, based on what drawoh described, that there are many ways to do things in Word, and most of them are wrong in the practical sense. Given how often the Word interface is drastically rewritten and reshuffled, I've been happy just to find a command that meets my need, much less the "best" function.

If anyone has some links to a best practices resource, that would be appreciated. (I don't mind buying one of those 1-2" thick books if it covers this question really clearly).

If we fail we'll be searching for another program.

 

[Oldhydroman]

I completely agree with SnTMan about graphics jumping all over the place in Word - but one little workaround (a typical "mechanical engineering" solution to the problem) is to put a table into the document and then paste the graphics into a cell in the table. The table can be a one-row/one column affair if needs be. If the table is then formatted to be without borders then no-one reading the paper/pdf form of the document will know how you cheated.

DOL

 

[MotionGirl]

Out on a limb here.
I use Help and Manual... It is a help authoring tool. Deals with graphic easily and can publish to paper, ebooks, as well as the web, and normal help files. VERY similar to instruction operation and maintenance manual requirements...