Technical Writing for Consultants who are involved in recommending solutions & evaluating systems & proposals.

1. Technical
Writing for
Consultants
Dilum Bandara
Dilum.Bandara@uom.lk

2. What We Do as Consultants?
• Conduct a need analysis
 Meetings, presentations, document analysis, phone calls
• Prepare a proposal
 Describe motivation & test/assessment procedure to be used
 Terms of Reference (ToR)
 Payment terms
• Conduct a solid test, assessment, investigation, or design
 Based on industry best practices & our own expertise
• Prepare a comprehensive report
 Test/assessment procedure used
 List findings
 List recommendations based on expert judgement
• Follow up meeting or presentation
 Call for action
 Help during action 2

3. Exercise
• Think about a test or assessment you did for a client
 Penetration test, security assessment, digital forensic
investigation, evaluate quotations, etc.
• Write a summary of the test or assessment including
 Test/assessment procedure
 Key findings
 Key recommendations
• Just write
 Don’t worry about spelling, grammar, or punctuation
 Don’t edit, just write
• 10 min max
3

4. Technical Writing
• Writing that
 “transfers information about a situation, product, service,
or concept… to audiences of varying levels of technical
knowledge, so that each member of the audience clearly
understands the message.”
• Word “technical” means skilled, specialized, &
strict
• Technical writing follows rules & protocols
4
- The Institute of Technical Communication (workshop) June, 1998
Source: www.zaetric.com/technical-writing/

5. Business Writing
• Writing style appropriate for a business setting
• Generally “persuasive” writing
• Purposes
 To convey information
 To explain/justify actions
 To influence reader to take some action
 To direct action
 To deliver good or bad news
• Includes
 Business Letters, E-mail Transmissions, Memo, Reports,
Contracts, MoUs, & Manuals
5

6. 6
Source: http://collegeunbound.org/2012/09/05/the-writing-process/

7. Rhetorical Triangle
7
Source:
https://rhetoricaljournalist.wordpress.com/2011/05/09/p
odcast-1-the-rhetorical-triangle-and-burkes-pentad/
Consultants
Experts
CIO
COO
IT Manager
Sys. Admin
Developers
State of system
Dos & Don’ts
Call for action

8. How To Do It?
• Write for at least 2 levels
 CIO, COO, IT Manager
 Sys. Admin, Developer
• Include all key points
 Findings & recommendations
 Clear scope
 What they need to provide to start project?
• Aim for precision
 Get straight to the point
 Don’t use unnecessary words or waffle
 Make every word count
• Unless you are a confident writer, best to avoid over-long
sentences
 Aim for a mixture of long & short sentences for variation & rhythm
8
Executive Summary
Bullets & Numbering
Tables
Diagrams
Details
Domain specific words
Annex with detailed
results
Tips & References

9. How To Do It? (Cont.)
• Avoid overly elaborate language
 Use technical language & words specific to your discipline,
where appropriate
 When using words that aren’t technical or domain specific,
use simple words in place of obscure words that have the
same meaning
 Using overly elaborate language can make your writing seem
pretentious
 “Write to express not impress”
• If there is any uncertainty about a particular point,
use cautious language
 e.g., ‘may’, ‘might’, ‘could’, ‘potentially’
• Avoid repeating the same words
9

10. How To Do It? (Cont.)
• Avoid vague terms
 Very high vulnerability, very high overhead, extremely important
• Use words efficiently
 Firstly, Secondly  First, Second
 Utilization  Use
 On the other hand  Alternatively
 Already existing, completely eliminate, basic fundamentals
• Write with verbs and nouns
 Active voice
 First person
• Appropriate format to improve readability
• Review
 Spellings, grammar, & style
 Peer review
10

11. Use Your Word Knife
• Readers are overloaded
• Use your limited word budget to get most
attention
• Types of readers
 Skimmers
 Read quickly
 Look for key words, bulleted information, graphs
 Summarize key points at beginning & end
 Skeptics
 Read every word
 Looking for logic flaws or reasons to disbelieve or say no
 Provide plenty of examples, details, & supporting statements
11

12. Examples
• Per our conversation, I am enclosing herewith a
remittance of $125 for the balance due on my
account.
• As we discussed, here is the $125 remaining on my
account.
• Here is the $125 remaining on my account.
• The relationship between the access to free contents and
loss of privacy in social networks is extremely important to
everyone including employees, businesses, government,
and general public.
• The conflict between free access and privacy in social
network concerns many employees, businesses,
government, and general public.
12

13. Examples (Cont.)
• Despite winning the game, the Sri Lankan team made
several errors in the field.
• Sri Lankan won the game, despite making several errors
on the field.
• Same observations are made from the Head Office
network also.
• Similar set of observations are to be made from the Head
Office Network.
• Slow response times are observed during different times
of a day while much higher delays are noted during peak
hours.
• Higher response times are observed not only during peak
hours but also throughout the day.
13

14. Examples (Cont.)
• We will utilize an efficient, top down root cause isolation process to
resolve the performance lag in the system.
• We (will) use a top-down process to diagnose performance issues in
the system.
• Proposal submitted for the Hosted Firewall by XXX PLC does not
satisfy the technical requirements, and does not satisfy the pricing
structure.
• The proposal submitted for the Hosted Firewall by XXXX PLC does not
satisfy the technical requirements.
• The Application allows XXXX employees to use the mobile work load
management system application on their day to day work activities
without coming to the brach it self.
• The Mobile App enables XXXX employees to access the workload
management system for their day-to-day work activities while on the
filed.
14

15. Exercise
• Read write up you wrote earlier (slide 2)
• Think about how to apply what we learned
• Edit/rewrite a summary of the test or assessment
including
 Test/assessment procedure
 Key findings
 Key recommendations
• 10 min max
• Let’s review write ups from 2-3 volunteers
15

16. To Be a Good
Writer You Must
Read