Get documents about "Getting your message across!!
Document Sample
Engineering your writing
“Words are, of course, the
most powerful drug used
by mankind.”
Rudyard Kipling
While drugs save lives everyday, they
have been known to destroy others!
January 09 C. Adams 1
Agenda
1. Why?
2. Word processing technology
A double-edged sword…
3. Engineering your writing
4. How not to write
5. Getting on with it
6. Tips
January 2009 2
Do I really have to write very often?
Getting your message across is critical:
E-mail
Resume
Biweekly Project Progress report
Design report
Technical Manual
Project Proposal
Salary review!!!
Required to make it through some courses!
January 2009 3
To get the job done:
You must articulate to yourself what you
want to say to others
You must communicate it the right way
(so they get it!)
You need to get the technical work done
You need to document it for the designers
as well as for the users!
January 2009 4
Documentation, Documentation, and then
Documentation
Everything starts with a proposal:
a Written proposal
Your only control over what people
understand is through how you articulate
your message
Technical writing is not like writing a
novel…
January 2009 5
What do engineers want to achieve
when they write?
Why are you writing this document?
Goal is to make your case, based on facts, and
convince people of the credibility of your conclusions
Product development
Users
Sales & marketing
Senior management
No room for imagination, feelings, suspense,
uncertainty about what will happen… the stuff that makes novels
great and leads to blockbuster movies is of no value
Once you start writing, holes start showing!
January 2009 6
Consequences of a Poor Attitude
Some technical writers think that
documents describing real hard-core
engineering cannot be clear by
definition…
This leads to technical documents that are
not understandable
This leads to the engineer’s goals not being
met!
January 2009 7
2. Word Processing Technology
• Too tempting to be “fancy”
• Can help with spelling, grammar
• Can add new typos (dangerous, embarrassing)
the>>ten, reduce>>seduce, bowl>>bowel
January 2009 8
Consequences …
• “I am very tolerant of people's ‘linguistic
challenges’ but when I read a document with
a lot of typos and cut and paste errors, I
immediately question the dedication and
responsibility of the person who wrote it and
wonder about the respect he/she has for the
intended reader.
If he/she did not take the time to proof-read
the work, why does he/she expect me to
invest the time to understand it?”
January 2009 9
Writing as an engineering design problem
Problem formulation
Design system A that receives your ideas as
input and produces an intermediate output: a
well-written document. This output is then
fed as the control signal into an existing
system B to ensure that System B’s output
meets desired specifications.
January 2009 10
3. Engineering your writing
Expertise of audience Decision:
Expectations from audience - Adopt the proposal
Time they allocated to read the work - Accept the design
Writing skills
Your
document
thoughts
January 2009 11
4. How to not write…
It has become clear to me that with regard to the
project we discussed yesterday, and after having
thought about the propositions you put forth, I am of
the opinion that there may be some difficulty in
meeting the precise requirements of the project
under consideration due to the fact that the team has
been laboring to meet deadlines in the near future.
In the eventuality that your deadlines, for the
platform being developed, are urgent, I would
probably recommend the consideration of the
utilization of an alternative approach, assuming that
your clients agree, for the development of the source
files needed for the system that is currently being
developed.
January 2009 12
5. Getting on with it
January 2009 13
Plan
What is my message?
Who is my audience?
What are my goals? What do I want them
to do after they understand my message?
Is there a required or expected template
for the document?
How much space (i.e., pages) do I have?
How much time can I invest in writing and
expect them to invest in reading?
January 2009 14
What is my message?
Why was this document requested?
Is my message to inform? Guide?
Recommend? Analyze? Sell? Test?
Communicate your message early on in the
document, clearly, concisely, on a high level
(abstract/executive summary)
Draw the sketch, then fill in the details
January 2009 15
Who is my audience?
What is their technical level?
What is their background?
What are their objectives?
Why are they reading my document?
To implement the code
To provide design review
To decide on funding the project
To use the product
January 2009 16
What is my goal?
What do I want the reader to do with my
message?
Fund the project or approve the design process?
Now that they accept my message, what
next?
Take the reader from agreeing with your
message to translating that into the action
you wish to happen
January 2009 17
Respect their time!
You are important but
you are NOT THAT important!
Meet their requirements/expectations or be prepared
to make the case for why you did not!
A longer document is less likely to be read than a
shorter one (unless they come to believe that your
writing is worth reading!)
If length is necessary and allowable, provide
executive summary, chapters, subsections,
conclusions, highlights,…
January 2009 18
Get to the point!
What not to do:
Describe a conference that is important,
costs, etc., but never explicitly ask for
authorization or justify why you should go
Send an e-mail to three people describing a
problem, and copy it to seven others
Ask for action but give no timeline
In your thesis, describe a lot of work but
never specify what you contributed or even
concluded
YOUR GOAL MUST BE STATED CLEARLY
If you do not know it, how will you
achieve it?
January 2009 19
Be accurate, clear, specific
Equation 2 describes the system where the variables
x,y are defined in the previous discussion
Vs.
Eq. 2 describes the proposed system, where x, y are
defined in Eq 1.3 in Chapter 1.
This system is ideally suited for you
Vs.
This system has been tested in the highest risk
scenarios 1, 2 and 5 and was shown to provide 50%
improved performance compared to the current
system. The performance was measured based on
the criteria in Equation 3.2
Opinion vs fact
January 2009 20
On clarity, ambiguity and vagueness
One unique message with no room for
interpretation or misunderstanding
Accept that the reader is NOT you; s/he
comes from a different perspective
Practice searching for an alternate
understanding (misunderstanding)
(Most examples are from “Writing as an engineer” by Beer and
McMurry, Wiley, 1997.)
January 2009 21
Vagueness and ambiguity
Pour the concrete when it is 40°C. ??
Before accepting the materials from the suppliers, we
must make sure they meet our standards. ??
The processor interfaced with the chip. It ran at
5Mhz.. ??
The group is very behind
We will be at least three weeks late in delivery
The team is overloaded
We are short 2 team members (i.e., 30% of our resources
are not available)
The chip outperforms its predecessor
The C22 is 50% faster than the C21 although the price is
the same
January 2009 22
Directness, simplicity = clarity
After a long and difficult development cycle
due to a death in the family of one employee,
the illness of another and parental leave of a
third, the new release will be somewhat late.
Vs.
The new release is 3 weeks behind schedule.
This is due to the unexpected absence of
three employees (see note 5)
January 2009 23
How not to write…
After a lot of discussion, the team, including
the support personnel, concluded that their
alternatives were to call in a consultant, who
had to be selected based on experience in
similar projects, thus increasing the cost of
the project, or having three more engineers
reassigned to the team from the C-group who
are having their own problems with resources
leaving no option but to call in the consultant.
January 2009 24
The team, including the support personnel, discussed this
issue at length. The team agreed that the only two
options are:
1. Ask for three engineers from team C to be reassigned
temporarily to the project.
2. Hire a consultant with direct experience in similar
projects.
Given that team C is already facing its own resource
problems, option 1 was dismissed. The team decided
to recommend hiring a consultant with direct
experience in the project even though this will increase
the project cost.
January 2009 25
Stay simple
Commence start
Compel force
Comprises is
Endeavor try
Procure get
Terminate End
I regret to inform you The action item is still
that the action item has not resolved
not been taken to
fruition
In view of the above therefore
In the event of If
Completely eliminate Eliminate
Collaborate together Collaborate
Alternative choices Alternatives
audit examines
January 2009 26
There is a story to tell…
The reader must see every section as a
response to the question that came into
his/her mind when they finished reading the
preceding section
Tell them where you are taking them. Tell
them when they get there!
E.g., In this section , we will discuss the
security aspects of the software and identify
possible threats……….
….. Now that we have identified the classes of
possible security threats in the proposed
system , we will investigate the necessary
measures to ensure the system can handle
such attacks.
January 2009 27
Be respectful
Avoid the use of “he”
in case he turns out to be a “she”
Avoid “it is obvious that”
it may not be obvious to your reader!
“It is obvious that the processor is fast enough.” vs.
“The processor runs at 5Mhz. This speed has been
shown to be sufficiently fast for this application.”
Avoid “everyone knows that”
in case your reader does not know that!
January 2009 28
Conclude
The conclusion has the high level description of what
you want them to walk away with
Summary
Briefly review the problem you were addressing and its
importance
Highlight the approach you used
Highlight how successful you were
Highlight possible concerns
Highlight what you plan to do next
Be realistic and honest. Acknowledge the weak link
rather than have them discover it!
You may fool them once or twice but you when you lose
credibility, gaining it back is DIFFICULT!
January 2009 29
6. Tips
Assess yourself. If you do not write well, start writing early.
Practice is the only way!
If people complain, they must have a reason. Do something
about it!
Plan enough time to write
Do not insult the reader: check spelling; verify grammar
Invest in reading your document for coherence, clarity,
structure, flow, etc. Time invested is directly proportional to
the consequences riding on this document!
If it is important, GET SOMEONE ELSE TO READ IT and tell you
if they got it! (Make sure they are better than you!)
January 2009 30
Engineering your writing
Bibliography
ELG/SEG 2911 textbook
“A Guide to Writing as an Engineer, 2nd Ed.”, by
David Beer and David McMurrey, Wiley, 2004
“Easy Access: The Reference Handbook for Writers,
2nd Ed.”, by M. Keene and K. Adams, Mayfield, 1999
http://www.sass.uottawa.ca/writing/
www.linguistic-funland.com/esloop/
January 2009 31
