Engineers as authors

Tue Oct 8 18:16:46 PDT 2013

When I started as a technical writer for Western Electric in 1978 the
requirement was that you had to have a technical degree to be hired. My
degree was in Electrical Engineering Technology. This requirement did not
change for quite a few years. We received the product engineering info from
the Engineers at Bell Labs. We took this info and created Task Oriented
Practices, Users Manuals, Installation Manuals etc. The Engineers were our
Subject Matter Experts and they review was we wrote. I am not sure if they
would have been happy taking their time away from development to actually
write these documents. 

Ann Z

-----Original Message-----
From: framers-bounces at lists.frameusers.com
[mailto:framers-bounces at lists.frameusers.com] On Behalf Of Helen Borrie
Sent: Tuesday, October 08, 2013 7:43 PM
To: Frame Users
Subject: Re: Engineers as authors

At 03:26 a.m. 8/10/2013, Stephen O'Brien wrote:

>Hi,
> 
>A few mechanical engineers have been asked, as part of their varied
workload, to author certain documents in English (How To, Webinars, software
essentials) in the near future.
> 
>Working with authors who are not formally trained is a new experience for
me. I am wondering how to best define their tasks and the tasks of my
technical writing group who will work together to ensure quality documents.
For example:
> 
>.         I could provide the engineers with templates in FrameMaker and an
introduction to the basics of technical writing and English grammar and
bring them to write good documents over time. Some formal training in
technical writing could be offered. The technical writers would then review
the final documents (container and content) to ensure the overall quality of
the documents.
> 
>.         Or, maybe the role of the engineers should be to write rough
content within guidelines (get the ideas and workflows on paper), and my
team of technical writers could be responsible for formatting the content
and expressing their ideas/workflows correctly in English. This would take
much less time for the engineer (less of a learning curve).
> 
>Do you have some experience in this matter? Any hints for what may work
best?

Is your task to train them to be tech writers or to be good informants?  Are
you tasked with producing the documentation or just with editing it? The
differences are crucial.  If they had meant to be tech writers, they
wouldn't (usually) have ended up as mechanical engineers.  And that's
discounting the built-in problem you possibly have there in Quebec, where
numbers of the engineers may not have learnt their composition skills in
English....

Remember that old adage: "Don't keep a dog and bark yourself."  What sense
would it make to hire a team of tech writers and then make the engineers
produce near-final content?

My best advice is to CONSULT THE ENGINEERS.  Between you, you have to
establish the reader audience and what needs to be got - from whom and by
whom -  in order to produce each of the docs.  That needs Q & A on both
sides, both initial and ongoing  The "how" will follow on once the basics
are clear.

The engineers will have their own distinct preferences as to the tool they
would use to deliver content to you.  In my experience, engineers often
don't "get" word processors and just use them like a text editor.  Making
them use Word templates is unreasonable for them.  Many prefer to use simple
text editors or email.  You can put them in the way of using a freely
available text editor like MS Notepad or free Notepad++ and offer elementary
training to those who want it.  

Give them plain-text templates with headings and blocks that cover the
information you've all agreed you need.  They can use those to build topic
outlines and, subsequently, to fill up with content.  On your side, you can
build your formal document outlines in Frame and "stuff them as you go".
The engineers are likely to be interested in the outlines of
sections/chapters/volumes for which they, individually, will provide
content.  Those may or may not be congruent with the organisation of the
published docs, so making and maintaining road maps may be a task for you
and your team.  A lot depends on the intended audience, change management
and other stuff they might not be involved in directly.

One place where you will need more source tool consistency is in figures,
especially if the company uses one main CAD tool.  Your tech writers will
need a tool for converting CAD output to Frame-friendly images if the
software itself doesn't provide one.

Helen

_______________________________________________

You are currently subscribed to framers as azdunczyk at triad.rr.com.

Send list messages to framers at lists.frameusers.com.

To unsubscribe send a blank email to
framers-unsubscribe at lists.frameusers.com
or visit
http://lists.frameusers.com/mailman/options/framers/azdunczyk%40triad.rr.com

Send administrative questions to listadmin at frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.