Welcome to TechWhirl Forums

Sign in or Register to get involved in our discussions.


Rebuilding a tech writing resource

Hello,

I'm a mechanical engineer in a company that produces industrial machines.  We're not a huge company and I don't believe we've ever had a trained technical writing specialist - our story is far from unique.  Our primary technical document is an Installation, Operation, and Maintenance manual for our machinery.  I'd love to hire a technical writer, but I estimate we have much less than a part-time job worth of workload.  Our customer base is a bit old school, so I anticipate us still producing a traditional manual for some years now, rather than structured online documentation.

Without getting into history, we currently have the IOM document files in Engineering.  They had been in Marketing, and they moved all of the documents to Word format - I suspect because they didn't understand the difference.  We've limped along and are planning to change this set-up, hence my interest in the expertise here.

I see several opportunities for improvement:

- Our documents in Word format are not done with strict formatting rules in Word.  As I'm sure you know, they can drive an ordinary user (me) nuts and lead one to making work-arounds to get the print to come out acceptably correct.  Editing them is very challenging because of these buried rabbit holes and the fact that each user applys Word formatting differently.  I'm thinking it would be wise to move over to a better software and clean up the formatting in the conversion process.  So what software would be a better match for our level of usage and training?  Or can Word be used efficiently if we simply re-train and standardize our usage?

- We have an individual interested in supporting this work as a part-time responsibility.  It seems to me we should plan for some training, get a style guide going, etc and that this investment will work out better than contracting the work.  Any suggestions for doing that?

- I did a little bit of research into the craft of Tech Writing and it seems that having a style guide would be immensely useful to clean and control our content.  Is there a style guide that we can borrow as a starting point?

- Our IOM template documents contain a lot of redundant information.  Changes in Terms and Conditions for example are difficult because they have been copy/pasted into dozens of documents.  I started with the Framemaker product page and it's awash with tech writing buzzwords that aren't in common English.  What technology / software can do this simply?

- Any other tips are appreciated.

Comments

  • JAlbersJAlbers United StatesPosts: 1
    We use Author It which lets us use the same content in multiple documents. I'm involved on the periphery, not actually using the software so I only know what grumbling I hear from the trenches. We used a consultant to convert our Word files to Author It but there was a lot of clean up to do (I'd estimate 1 person year for 2000 pages across 4 main documents). 

    Our company uses a style guide that is 40 pages or so long (35 pages too long in my opinion). Contributing authors follow it a bit but then it takes our word processing person to publish. 

    Sorry, not much concrete help but I feel your pain. 
    Good luck. I hope someone can give you some true guidance. 
  • AMosesAMoses United KingdomPosts: 4

    Hi, as a basis, you could use the Microsoft Manual of Style. It's extensive (might have more information than you need) but very good. I don't think it's available as a PDF, but you can buy the printed version. I still use it on a regular basis to look up stuff.

    Using Word for large documents is a pain, especially if you're including images. We are using FrameMaker, which is more complicated, but probably worth the switch in the long run. Once you know the basics, it's easier to use and the output looks much better. That said, I don't know other editing tools so can't really suggest anything else.

    Good luck! 

  • Thanks for the feedback.

    I purchased a couple of tech writing books:

    http://www.amazon.com/Technical-Documentation-Basics-essentials-technical/dp/3943860000

    http://www.amazon.com/Technical-Documentation-Solutions-Instructions-understands/dp/3943860086/ref=asap_bc?ie=UTF8

    They seem to cover the basics of writing style, at least in my layman's understanding.  I'm considering using these as our ad hoc style guides.

    Or does a proper style guide also cover things of visual style, such as things that might appear in templates?

    The more I read about Framemaker convinces me it's amply capable and well suited, except I don't want to end up with only one or two people able to use it.  I'm hearing good things about MadCap Flare.

  • Cathe_BedardCathe_Bedard United StatesPosts: 2
    Hi!

    Did you get a free trial of MadCap Flare, and if so - how did you like it? I'm researching MadCap Flare as a possible tool to use in consulting, but would like input from you or anyone else on this list before I commit my time to the trial.

    thanks,
    Cathe
Sign In or Register to comment.