A presentation on basics of technical writing for new technical writing entrants in my current organization.

1. Introduction to Technical
Writing
PRITI GAIKWAD DHENDE

2. Agenda
 Definition of Technical Writing
 Difference between Technical and Creative Writing
 Technical Writing Deliverables
 Software and tools
 Style Guides and standards
 Document Development Life Cycle
 Technical Writing Tips
 Dos and Don’ts
 Quality of Technical Documentation
 Characteristics of a good technical writer
 Exercises

3. Definition of Technical Writing
 Technical writing involves:
 creation of technical content
 in a concise, readable and structured format
 to a specific intended audience.

4. Technical vs Creative Writing
Technical Creative
Content facts and figures Imagination, fiction
Audience specific general
Purpose instruct, train, sell entertain, inspire, express
Style formal, restricted informal, artistic
Tone objective subjective
Vocabulary specialized general, unrestricted
Organization sequential, systematic arbitrary, artistic

5. Technical Writing Deliverables
Printed Documentation
User Guides
Training Manuals
Operation and Maintenance Manuals
Safety Manuals
Quick Reference Guides
Installation Guides
Administration Guides
Online
CHMs
WebHelp
Responsive HTML
HTML5
Training and marketing content
Technical Reports
White Papers
Training videos
Brochures
Case studies

6. Software, Tools, and Techniques
Documentation
Software
•ArborText Editor
•Adobe Framemaker
•Adobe RoboHelp
•Madcap Flare
•Microsoft Word
•Oxygen
•Xmetal
•CitecFemton
Visualization tools
•Adobe Illustrator
•Adobe PhotoShop
•CorelDraw
•Microsoft Visio
Screen Capturing tools
•SnagIT
•Snipping Tool
Content Management
System
•Tortoise SVN
•SDL Knowledge
Center
•CitecDot
•PTC Windchill
•WordPress
•Joomla
•CitecFemton
Frameworks, Principles
•Information Mapping
•DITA

7. Style Guides and standards
 ASD STE-100 Simplified Technical English
 Microsoft Manual of Style for Technical Publications (MSTP)
 Chicago Manual of Style
 S1000D
 Interactive Electronic Technical Manual
 MIL-M-87268: Manuals, Interactive Electronic Technical: General Content, Style, Format,
and User-Interaction Requirements
 MIL-D-87269: Data Base, Revisable: Interactive Electronic Technical Manuals

8. Document Development Lifecycle (DDLC)
Planning
•Requirements
Gathering
•Audience Analysis Designing
• Deliverables
• Tools, style guides
• Templates
Creating content
• TOC
• Iterative content
Reviewing
• Technical
• Editorial review
Integrating feedback
Publishing & Compiling
Maintaining versions

9. Technical Writing Tips
 Understand the scope
 Know your audience
 Do your own research
 Plan well
 KISS
 Define structure first
 Use Active voice
 Write clear instructions

10. Understand the scope
 Purpose of the document
 What?
 How?
 How much?
 Define what is Out of scope

11. Know your audience
 Ask questions about background, technical and language skills
 Interview, if possible and ask questions
 Identify expectations

12. Do your own research
 Try to access all available documentation
 Read before writing
 Do your own investigations
 Frame questions only if you do not find answers
 Maintain query tracking lists

13. Plan well
 Identify main goal
 Divide tasks and sub tasks
 Estimate each task
 Maintain a plan and keep it updated
 Create an outline
 Write iteratively
 Create initial draft
 Revise and proofread
 Integrate feedback
 Estimate ample time for revisions and feedback management

14. Keep it Short and Simple
 Do not use three words where two are enough.
 For example:
You can click Ok. 
Click OK.
Wait till the pressure reaches 7 bar and then shut down the engine. 
When the pressure reaches 7 bar, shut down the engine.

15. Define structure first
 Develop the Table of Contents (TOC)
 Get it approved
 For entire documentation projects:
 Maintain a tracking sheet for the TOC
 Ensure all the heading levels
 Identify sections that can be started in advance
 Manage project effectively by raising concerns on delays

16. Use active voice
 Active
 Direct
 Clear
 Examples:
 You can always develop your technical
writing skills on the job.
 Stop the engine.
 Check for possible wear and replace
worn parts, if necessary.
 Passive
 Indirect
 Unclear
 Examples:
 The writing skills can be developed on
the job.
 The engine can then be stopped.
 The wear and tear of the parts can be
checked and then they can be replaced.

17. Write clear and sequential instructions
 Identify the result
 List down the prerequisites
 Write the instructions in a logical flow
 For procedures with a sequential flow,
use numbering lists:
 Instructions to be performed in a
specific order
 Chronological order of events
 For non-sequential instructions, use
bullets:
 List of features
 Organize a list or array of information
 Steps that do not have to be
performed in a specific order

18. Ordered lists vs Unordered lists
 Numbering lists
 Example:
Checking for wear and tear
1. Open the flexible coupling (2) fixing
screws.
2. Dismantle and clean the coupling.
3. Check for possible wear and replace
worn parts, if necessary. worn parts, if
necessary.
 Bullets
 Example:
This application has the following features:
 Robust
 Secure
 Optimum ROI

19. Write clear and sequential instructions
 Important instructions that needs to be brought to user attention can be written
as:
 Notes – Emphasize important information
Examples:
Note: All parts should be checked before using them.
Note: An error message is displayed, if you enter wrong inputs.
 Warning/Danger/Hazard – Can be fatal to user or damage system beyond repair.
Warning: Working without safety gear may prove fatal.
 Caution – Can damage equipment
Caution: Not tightening screws correctly, may cause damage to the spare part.

20. Dos
 Use of first person -
 You must check all the prerequisites
before starting this procedure.
 Start the engine.
 Culture neutral - no country specific,
religion specific negative examples
 Gender neutral - no he/she – use
plural forms
 He can download all the tutorials. 
 They can download all tutorials. 
 Citations and references – always refer
to the original source
 For more information, see ….
 Illustrate to explain better -
 Tables
 Charts
 Figures
 flowcharts

21. Don’ts
 Jargons
 Plagiarism
 Decorative languages
 Redundant information
 Additional information that is out of scope
 Offensive content

22. Dos
 Maintain consistency in:
 Headings - gerunds preferred
 Introducing Technical Writing
 Logging into the system
 Testing the appliances
 Subject verb agreement
 You can replaced the parts if they show wear and tear. 
 You can replace the parts if they show wear and tear. 

23. Typical Technical Documentation structure
 Cover page
 Copyright
 Revision history
 Table of Contents
 Chapters
 Appendix
 Glossary
 Index

24. Typical chapter structure
 Chapter 1 - Introduction
 About
 Scope
 Intended Audience
 Key Features
 Chapter 2 – Getting Started
 How to access
 Login/Logout (Start and shutdown)
 Rest of the chapters - functionalities

25. Attributes of good Technical
Documentation
 Technically accurate
 Grammatically correct
 Complete and fulfils its purpose
 Well-organized structure
 Clear instructions and concepts
 Contains relevant information
 High usability ratio
 Visual aids used, where required
 References, citations and credits given
 No redundancy or extra information

26. Characteristics of a good Technical Writer
 Proactive attitude
 Proficiency in the English language
 Skilled in documentation tools and techniques
 Sufficient domain knowledge
 Good writing skills
 Effective communication skills
 Good team player
 Able to work with many stakeholders to get the project
complete
 Analytical and logical thinking process
 Eagerness to learn and research
 Ability to work with changing timelines
 Troubleshooting and problem solving abilities
 Adaptable mind set
 Assertive and able to communicate negative information
 Accepts feedback constructively
 Ready to revise content for better output
 Capable of finding better ways to reduce timelines and effort
required