Technical

Writing
Complete Training
Abdul Ghani Shahzaib

Document Information
Category
Document
Version
Author
Reviewer
Approver
Issue Date
Distribution
Document
Category
Privacy Level

Information
Technical Writing Complete Course
Draft
Abdul Ghani Shahzaib
22-11-2016

Internal
Public
Confidential
Customer
This document contains confidential information.
Do not distribute this document without prior
approval.

Disclaimer

Review History
Sr #

Review Team

R/V Date

Conclusion

Remarks

Date

Section
Changed

Description

Modification History
Version

Author

Table of Contents
1.

Technical Writing.......................................................................................... 3

2.

Software Development Life Cycle - SDLC.....................................................3

3.

Technical Writing Process.............................................................................3

4.

Document Delivery Life Cycle - DDLC..........................................................4

5.

Document Deliverables................................................................................4

6.

SME Interviews and Project Planning............................................................4

7.

HTML & XML Intro......................................................................................... 5

8.

Writing Skills................................................................................................. 5

9.

Style Guide and Standards...........................................................................5

10.

Technical Writing Software Tools...............................................................5

11.

Grammar................................................................................................... 5

12.

Microsoft Word Word Processing Tool......................................................6

13.

Adobe RoboHelp Help Authoring Tool.....................................................6

14.

Adobe Frame Maker Technical Content Publication Tool..........................6

15.

Snag IT Image Capturing Tool.................................................................7

16.

MS- Visio - Image Drawing Tool.................................................................7

17.

PowerPoint - professional presentation tool..............................................7

18.

Photoshop Image Editing Tool.................................................................8

19.

Reviews, Delivery and Publication.............................................................8

20.

Resume Preparation and Certification.......................................................8

Technical Communication Detailed Course Outline..........................................9

Module 1: An Introduction to Technical Communication (4 hours)...................9
Module 2: Software and Document Development Life Cycles (4 hours)..........9
Module 3: Elements of Technical Documentation (6 hours).............................9
Module 4: Information Organization and Design (2 hours)............................10
Module 5: DDLC Deep Dive (6 hours)............................................................10
Module 6: Essentials of Writing (8 hours)......................................................11
Module 7: Technical Communication Tools (1 hour).......................................11
Module 8: Advanced Concepts and Trends (1 hour).......................................11
Module 9: Assessment................................................................................... 11
Training booklets designed by Technowrites's team......................................11
Mapping Documentation Development Life Cycle (DDLC) with SDLC..................12
Mapping Documentation Development Life Cycle with SDLC...........................14

What is Instructional designing?.......................................................................16

Evolution of Instructional Designing..............................................................16
Why Instructional Designing..........................................................................16
What does an Instructional Designer do?......................................................16
How is it done?.............................................................................................. 16
Can I become an Instructional Designer?......................................................17
A Teacher This will help one plan and conduct classes in a systematic manner
keeping the Students (audience) in mind and not blindly follow the syllabus
structure........................................................................................................ 17
A Trainer........................................................................................................ 17
A Project manager......................................................................................... 17
Commercial Designers................................................................................... 17
Journalists...................................................................................................... 17
Creative Writers/Editors/Authors...................................................................18
Do I need any special skills?..........................................................................18
How to become a good instructional designer? -Problem with traditional
approach of ID:.............................................................................................. 18
Type of Documents........................................................................................... 19
Tool Expertise................................................................................................... 19

Technical Writing Techniques

1. Technical Writing
2. Software Development Life Cycle - SDLC
3. Technical Writing Process
4. Document Delivery Life Cycle - DDLC
5. Document Deliverables
6. SME Interviews and Project Planning
7. HTML & XML Intro
8. Writing Skills
9. Style Guide and Standards
10.
Technical Writing Software Tools
11.
Grammar
12.
Microsoft Word
13.
Adobe RoboHelp
14.
Adobe Frame Maker
15.
Snag IT
16.
MS- Visio
17.
PowerPoint
18.
Photoshop
19.
Reviews, Delivery and Publication
20.
Resume Preparation and Certification

1. Technical Writing

What is Technical Writing?

Role of a Technical writer
Principles of Technical Writing, Documentation deliverables
Printed documentation and Online Help Systems
Working with images and illustrations

2. Software Development Life Cycle - SDLC

Software Development Life Cycle

How Software is developed, tested, maintained and retired
How products are installed, configured, customized and deployed
Relating software product features and business benefits
Working with programmers and testers
Understanding software requirement specifications
Analysing product architecture
Documentation development life cycle
Types of documents associated with software products
Different types of software and applications

3. Technical Writing Process

Understanding Audience/Readers
Collecting and Organizing information
Drafting information verbally and visually
Producing Information

4. Document Delivery Life Cycle - DDLC

Document development process

Estimating Technical Documentation
Documentation Planning
Selection of Tools
Information Architecture
Templates and Page design
Audience Profiling
Task Analysis
Content Development
Elements of Style
Technical Reviews
Editorial Reviews
Formatting and pagination
Document Conversions
Content Publishing
Quality Control
Content Maintenance

5. Document Deliverables
Types of Software/Hardware documents
a. End-User documents
User Manual, Administrator Guide, Online Help Files
Quick Reference guides, Release Notes, Read Me Notes
Training Presentations, Deployment /Installation Guide
b. Technical Documents
Functional Requirement Specification (FRS)
System/Software Requirement Specification(SRS)
Application Program Interface (API)
Design/Architecture Documents, Project Plan
c. Marketing and Web Documents
Case Studies
White Papers
Proposals/ Success Stories
Product Briefs/Brochures

6. SME Interviews and Project Planning

Role of SME
SME objectives
SME interviews
Purpose of SME interview
Types of SMEs
Technical Writer and SME interactions
How to conduct SME interviews?
Modes of communication with SME
How to gather information from SME
How to create documentation Checklist
SME reviews

How to create project plan

Tips for conducting SME interviews

7. HTML & XML Intro

Why HTML
HTML Document Structure
HTML Tags
HTML importance in Technical writing
Styles and CSS
Why XML for Technical Writers
XML Vs HTML
Introduction to XML
Introduction to DITA and single sourcing

8. Writing Skills

How to write clear and concise sentences

How to Write Steps, Instructions and Procedures
Organizing the content
Using simple words/Plain English
Logical sequence of Writing
Writing Sentence and Paragraph
Words to Avoid in Technical Writing
Document Flow
Tone and Rhetoric

9. Style Guide and Standards

10.

What is Plagiarism
Steps to ensure Plagiarism free content
Types of Style Guides
Documentation Standards
Microsoft Style Guide for Technical Publication (MSTP)
Plan your writing
Document Conventions

Technical Writing Software Tools

11.

Microsoft Word Text Editor

Adobe RoboHelp - Help Authoring
Adobe FrameMaker Content Publication
Snag IT Image Capturing
Ms Visio Image Drawing
PowerPoint Training Presentation
Adobe Photoshop Image Editor

Grammar

Punctuations and Mechanics

Capitalization
Active Voice and Passive Voice

12.

Microsoft Word Word Processing Tool

13.

About Microsoft word

Introduction
Features
Starting the Application
Accessibility, Formatting Text
Font and Paragraph settings
Bullets and Numbering, Cross-references
Borders and Shading, Styles and Formatting
Template Creation, Creating Sections
Working with Table, Bookmark &Hyperlink
Generating Table of Contents & Table of Figures
Header and Footer, Footnote and Endnote
Working with Reviewing toolbar
Toolbars, Shortcuts, Protecting the Document
Watermarks/Columns/Change Case
Generating Index, Auto text and AutoCorrect

Adobe RoboHelp Help Authoring Tool

14.

Writing clearly and concisely

Editing content, grammar and syntax
Proof Reading
Grammar Practice and Assignment
Email Etiquettes

About Online Help

Planning an Online Help, Understanding RoboHelp Interface
Creating your First Help project, Working with Topics & Folders
Working with TOC, Index, & Glossary, Generating Output
About Types of Layouts, Applying Template and Style Sheet
Controlling CHM Window and Skins
Working with Links, Pop-ups, Triggers, and Drop-downs
Working with Graphics and Text boxes
Creating Related Topics, See Also and Keyword Link
Playing with Marquee, Triggers, and Splash Screen
Creating Dropdowns, Expanding, Hyperlinks and Popups
Changing the primary layout, Tools in RoboHelp Html
Creating and Working with Tables, Creating and Displaying Browse
Sequence
Creating Manually/Automatically Multiple TOCs, Indexes, and Glossaries
Single Sourcing - Conditional Build Tags and Batch Generation
Creating Context-sensitive Help, Importing Files & Skins, and Merging CHM
Understanding the Project Source Folder and Files
Generating Reports

Adobe Frame Maker Technical Content Publication Tool

Introduction
Usage of FrameMaker
FrameMaker v/s MS Word

15.

Getting Started, Accessibility

Creating/Importing Documents
Saving New File Formats
Basic Text Formatting
Working with Tags, Tables
Tools Palette, Drawing Tools
Working with Paragraph and Character Designers
Working with Frames, Anchored Frames and Alignments
Working with Body, Master and Reference Pages
Page Designing and Defining Variables
Hyperlink, Cross Reference, Pop-Ups and Image Mapping
Generating Table of Contents, Index and Glossary
Creating Books, Conditional Text and references
Document Conversions

Snag IT Image Capturing Tool

16.

About Snag IT
Introduction
Features
Starting the application
Image Formats, Batch Convert Images
Exploring the Program Window
Capture Profile, Image Capturing Modes
Creating WebPages, Creating simple Demos
Companion Applications
Snag IT Editor
Snag IT Studio
Catalog Browser

MS- Visio - Image Drawing Tool

17.

Introduction to MS- Visio

Using various technology images
Creating DFDs and Architectural Diagrams
Synchronization of images
Creating different file formats
Special Merits, Installation sequence
Types of shapes, Behaviour of shapes
How to Get shapes, Templates stencil
Connection shapes, Staking shapes
Group/ Ungroup, Text Adding
Data Linking, Data Graphics
Auto Linking, Hyper Linking
Save type formats
Importing into Word

PowerPoint - professional presentation tool

Importance of Presentations
Saving PowerPoint
Working on Slide Master
Applying Design Templates
Custom Animation and slide transition effects

18.

Action buttons and hyperlinks

Slide layouts, Movies and Sounds
Insert & edit clip art
Create a slide background using a picture
Customize graphical bullets
Insert and format a table into a slide
Add an animation scheme to selected slides
Rearrange slides, Slideshows
Customize slide backgrounds and templates

Photoshop Image Editing Tool

19.

Introduction to Photoshop
Cropping images and editing
Using advanced tools for creating architectural diagrams
Explore the Photoshop Environment
Basic Photo Corrections, Selections
Basic flow mode for editing images using Photoshop
Retouching and Repairing
Work with selections
Creating layers, Mask and Channels
Correcting and Enhancing
Slice and Link an Image
Creating Rollovers, Animate GIF Images
Painting and Editing
Basic Pen Tool Techniques

Reviews, Delivery and Publication

20.

What is a review cycle?

Types of Reviews
Who are the different people involved in a review?
How to implement reviews
Life cycle of reviews
Delivery modes
Delivery methods
Printable Document and Online Documents
Editing, formatting Proof Reading techniques
Format documents to enhance communication and visual appeal
Version Control System

Resume Preparation and Certification

Students Query handling

Mock interviews and industry orientations
Writing Assignments, monitoring and Feedback
Online Test
Certification

Technical Communication Detailed Course

Outline
=====================

Module 1: An Introduction to Technical Communication (4 hours)

Overview of technical communication

Various forms of writing
Brief history and relevance of technical communication
Classification of technical documentation
Characteristics of good technical documentation
Scope and career prospects in technical communication
Essential skills of a technical communicator

Module 2: Software and Document Development Life Cycles (4 hours)

SDLC Definition and benefits
Phases of a software development life cycle (SDLC)
o Requirement analysis
o Design
o Development
o Integration and testing
o Installation and deployment
o Maintenance
o Decommission
Types of software development life cycles
DDLC Definition and benefits
Phases of a document development life cycle (DDLC)
o Requirement gathering
o Designing
o Planning
o Developing
o Reviewing
o Publishing
o Maintaining
SDLC and DDLC mapping

Module 3: Elements of Technical Documentation (6 hours)

Taxonomy of documentation deliverables
o Installation and configuration guides
o Administration guides
o End-user guides
o Developer documents
o Troubleshooting guides
o FAQs
o Online help systems

o Release notes
o White papers
o Hardware documentation deliverables
Anatomy of a book
o Title page
o Legal notices, trademarks, and copyrights
o Table of contents, list of tables, and list of figures
o Preface (include nomenclature and terminology)
o Chapters (include parts)
o Appendices
o Glossary
o Index
Types of delivery formats
Differences between print and online documentation

Module 4: Information Organization and Design (2 hours)

Information organization
o Top-down approach
o Bottom-up approach
Information design elements
o Tables, flowcharts, procedures, illustrations, checklists, and so on

Module 5: DDLC Deep Dive (6 hours)

Part A: Creating Documents
Requirement gathering
o Gathering requirements
o Interviewing subject matter experts
o Performing user and task analyses
Designing
o Identifying the documentation set
o Designing documentation outlines
Planning
o Assessing effort and scope of work
o Developing a documentation project plan
o Selecting tools
Developing content
Reviewing content
o Technical, self, peer, functional, and editorial reviews
Publishing content
Part B: Revising Existing Documents
Requirement gathering
o Same as Part A
o Analysing impact and scope of change
Designing
o Redesigning documentation outlines

Planning (same as Part A)

Developing content (same as Part A)
Reviewing content (same as Part A)
Publishing content (same as Part A)
Maintaining content

Module 6: Essentials of Writing (8 hours)

English grammar essentials

Basic differences between American and British English
Principles of technical writing
Style guides

Module 7: Technical Communication Tools (1 hour)

Authoring tools
o Printed documentation
o Online documentation
Image-editing tools
Publishing systems
Mapping of the DDLC with tools used

Module 8: Advanced Concepts and Trends (1 hour)

A brief introduction to DITA
Minimalism
o Localization
Social media participation
New-age content types
o Videos
o Mobile docs
o Wikis

Module 9: Assessment
Project submission
Oral assessment (panel of experts)
Examination

Training booklets designed by Technowrites's team

Technical Communicators
Starter Kit
O Writing Templates
o Review Guidelines
o Publication Guidelines
o QC Sheets
o Estimation Sheets
o Project Planning Sheets
o Ratio Analysis Guidelines
o Screenshot Guidelines
o Table Guidelines
o Samples of Good/Bad Resume

o Much more...

Mapping Documentation Development Life

Cycle (DDLC) with SDLC
Software Development Life Cycle is a sequence of phases or logical stages in the
course of development of an idea into a software application or a product. It is commonly
abbreviated as SDLC. A well-known traditional approach to SDLC is known as
Waterfall Model. The Waterfall Model lists the stages in the life cycle as:

1.
2.
3.
4.
5.

Communication (Project Initiation, Requirements Gathering)

Planning (Estimating, Scheduling, Tracking)
Modeling (Analysis, Design)
Construction (Code, Test)
Deployment (Delivery, Support)

For any software application to be developed, the development team isnt just
constituted of software engineers, analysts, and architects. It also requires
people to test and document the processes as well as the product. The group
that works on creating and maintaining documentation is known as
Documentation or Technical Publications group and it is composed of Technical
Writerspeople who can create Technical and User Documentation.

The Technical Writers also follow a development cycle for creating

documentation, which is known as Documentation Development Life Cycle. The
Documentation Development Life Cycle (DDLC) maps with the SDLC such that
the entire product team works in close coordination to complete the

development, adhering to a common project schedule. Modelled on SDLC, the

DDLC has somewhat similar stages as that of SDLC. However, the duration of
stages varies according to the difference in availability schedule of inputs for
various stages. Let us begin with taking a look at the stages in the DDLC.
The DDLC stages, as understood by Technical Writing team at Ascezen, include
the following

1.
2.
3.
4.
5.
6.

Understand Requirements
Design
Develop
Review
Finalize
Publish

The activities to be performed during each of the stages are listed below:
1. Understand Requirements
o Understand the Product or Application to be developed
o Gain an understanding of the Domain or Subject Matter
o Understand Client Requirements for Documentation
o Study Legacy Documentation and Writing Style Guides used by the
Client
o Provide Content Consulting or Evangelism
o Propose Documentation Deliverables and Tools to be used
o Prepare Effort Estimate
o Propose Team Size and Composition
2. Design
o Prepare Templates and Stylesheets
o Prepare an Outline or the Table of Contents for documents to be
created
o Create Content Strategy for Single-sourcing or writing for multiple
user roles
o Create a Documentation Project Schedule
3. Develop

Gather Information: Read Design Specifications, Interview Subject

Matter Experts (SMEs)
o Create Content Drafts
o Create and Insert Graphics
o Format the Content
o Generate Output(s)
4. Review
o Language Review
o SME or Technical Review
o Client POCs Review
5. Finalize
o Incorporate agreed changes after each review
o Finalize the Content
6. Publish
o Integrate the Documentation with the Product or Application
o Send for final publishing or distribution
o

Mapping Documentation Development Life Cycle with SDLC

Mapping the Documentation Development Life Cycle (DDLC) with the Software
Development Life Cycle (SDLC) isnt as straightforward as it seems. Some of the
reasons are:
1. Documentation starts quite late in the SDLC: Most often, the last few to
get on board a project are the documentation people. Even if they arent,
the requirement understanding stage for technical writers is extended till
the time they get to read a formal requirement specification document or
see a prototype. However, it doesnt happen like that always as
sometimes technical writers get to document the design specifications
too.

2. Documentation cant finish as soon as the Software Development: It is

only when the entire software application is developed that the

documentation can be given its final shape. Even after all the content in
created, there are activities such as language and SME reviews, creating
index entries, generating and testing final outputs. All this may take some
time until we can announce the completion.
3. Trivial Changes in the Application may call for Critical Documentation
Updates: Small changes such as change in UI resulting in relocation of a
button or field, modification in input type on a form, reorganization or
reordering on menu may account for an unexpected volume of change
across the documentation. It might also require recapturing and replacing
numerous screenshots.
With the above factors, the DDLC may not have all its stages completely go
hand-in-hand with the SDLC stages. The Requirement Understanding stage of
DDLC goes on till the commencement of Construction or Development phase of
SDLC. Typically, there would be a lag in Documentation Finish dates and the
DDLC would extend the duration of SDLC, too.

What is Instructional designing?

Instructional designing can be defined as a systematic process of applying
scientific principles to the planning, design, creation, implementation and
evaluation of an effective and efficient instruction material/strategy.
In a laymans language Instructional Design is the plan of action with a purpose
Instructional Designing can also be called as

Instructional Development

Instructional Technology

Educational Technology

Evolution of Instructional Designing

Instructional designing is a Military concept that evolved during World War II
when the US military was faced with an erroneous task of training large
workforce to perform complex technical tasks, from field-stripping a carbine to
navigating across the ocean to building a bomber
Tasks were broken down into subtasks, and each subtask was treated as a
separate learning goal.
Training was designed to reward correct performance and remediate incorrect
performance. Mastery was assumed to be possible for every learner, given
enough repetition and feedback. After the war, the success of the wartime
training model was replicated in business and industrial training, and to a lesser
extent in the primary and secondary classroom. The approach is still common in
the U.S. military.

Why Instructional Designing

Instructional designing is a learner centric methodology which aims at maximum
knowledge transfer in the least possible time simultaneously balancing
conceptualization and retention power of the audience in equal measure. It is
done by applying the psychological principles and empirically derived procedures
to design materials.

What does an Instructional Designer do?

An Instructional designer is an architect of a learning material who
Helps learners comprehend new information received
Adapts existing technology to make learning transparent and functional for
the audience
Works with the subject matter expert to determine the effectiveness of the
materials produced
Visualizes the output in order to lay down an effective framework for the
course content
And finally justifies the purpose of content design.

How is it done?
It is done by
Drafting a production schedule
Designing the course
Structuring the text and checking the details so that it is ready for printing
Scheduling review sessions with subject matter experts (SME)
Checking whether the course contents are appropriately and accordingly
linked
Controlling the process of course development
Arranging for the field testing of the course
Preparing materials for the final output
Executing the final output

Can I become an Instructional Designer?

Anybody can become an ID because it is all about transferring knowledge in the
most the appropriate manner.
Listed below are a few professions

A Teacher
This will help one plan and conduct classes in a systematic manner keeping the
Students (audience) in mind and not blindly follow the syllabus structure.
Advantages
ID will familiarize and assist them in understanding the learning needs of
children. Planning and teaching them will become a less arduous task
Children can be given the best education by blending technology and the
theories required to understand certain behaviours. Also by imparting
knowledge through an appropriate media
Developing interest of the students
Increasing their retention power
Get better results from the class

A Trainer
ID will help a trainer design/construct a curriculum/training in a scientific manner
and deliver effective content through technology in diverse ways.
Advantages
Planning/conducting a training more effectively
Designing an appropriate training material to meet the requirements of
the team/training
Transfer requisite knowledge at a desired pace
Increase the learner base by upgrading the training methods to current
trend

Conduct quizzes/surveys/tests to gauge the knowledge transfer and the

learning curve

A Project manager
ID will help a project manager plan the deliverable meticulously and make
precise decisions
Advantages
Plan the outline of the project more effectively
Help get a detailed insight of the project
Deliver the output through an appropriate media.

Commercial Designers

ID will equip commercial designers to visualize the quality of the output and give
them an edge over the others
Advantages
Have a very clear picture of the output
Design a product more decisively
Create a greater impact on the customer by creating visually stimulating
products

Journalists
ID will assist journalists to draft the content captured more scientifically by
weaving language and ID concepts together to have a more striking impact on
the audience
Advantages
Structure the content more judiciously
Identify the criticality of an issue and deliver the information accordingly
while bearing in mind its impact on the people.

Creative Writers/Editors/Authors

ID will add flair to their writing by familiarizing them with the behavioural aspects
of the human mind thus making their writings more objective.
Advantages
Add the flavour of technology to writing
Visualize the audience impact while developing content
Reduce the time spent on testing the quality of the content

Do I need any special skills?

Though a specialized skill set is not required from an Instructional designer, it
would be an added advantage if one can have the following
Process Flow abilities - To think and act through strategic process, of content
and instruction, project management
Research and evaluation skills - with a focus on continuous improvement
Learning theory knowledge - To address learning through instruction,
consistently thinking about learning as an outcome of all instructional activities
Interpretation skills and flexibility - To assess and adjust to any situation
with a focus on learning and performance improvement.
These skills can and will be learned because instructional designing at TechTotal
embeds them in you as the course takes you along
The Plus Points
Instructional designing is such a process that it makes an individual
Pragmatic in his approach
Prudent in his decisions

Creative in his ideas

Analytic in his judgment

How to become a good instructional designer? -Problem with traditional

approach of ID:
The theory of instructional design is different from the practice and vice versa.
A good instructional designer requires a keen knowledge of theory and a
practical way to apply it and see it work.
Learning has to come from many sources. If we stick exclusively to theory, well
be unprepared to break out of the sterile academic environment and actually put
our knowledge into practice.
Learning must include a wide variety of opinions and backgrounds, as well as
real-world experience.
The traditional approach of training followed during the past few years has
created a gap between theory and practice.
But, unfortunately most of our teachers or institutes never bothered to bridge
the gap between the two.
Blooms taxonomy Is it practical?
Blooms Taxonomy comprises of six learning levels that are arranged in an
ascending order. These levels are:
o Knowledge
o Comprehension
o Application
o Analysis
o Synthesis
o Evaluation
Just listing the verbs associated with Blooms Taxonomy will be of no practical
help and mere definitions of the six levels will be of scarce use.

Type of Documents

User Guides
Online Help (all formats)
Web Help
Training Materials
Website Content
Programmer's Guides
Administrator's Guides
Installation Guides
Technical Reference Manuals
Release Notes
Process Documentation
Template Creation
System Design Documents
Assembly Manuals
Maintenance Manuals

Software Manuals
Testing Documents
Technical Writing Training
Quick Reference Guide
API Documents
SRS/BRS/FRS/RFP
Computer Based Training
Proofreading
Template Designing
Document Conversion
Prototypes
Simulations
Training Presentations
e-learning Materials
Video demonstrations

Tool Expertise

Ms Word
Adobe FrameMaker
Ms Office
Adobe RoboHelp
Photoshop
Madcap Flare
DoctoHelp
Adobe Acrobat
Epic Editor
MS Visio
HTML Workshop
Epic Editor
Articulate
Adobe Indesign
XML Editors

Camtasia
Adobe Captivate
RationalRose
WebWorks Publisher
RoboDoc
PageMaker
Illustrator
HTML
Flash
FrontPage
AuthorIT
DreamWeaver
Zabgrabber
Corel Draw
WebWorks
Snag IT