Writing Technical Documents

[Technical Documentation]
Dr. G. Venkatraman
 Writing Technical Documents

Technical Documentation – A Definition

‘Technical documentation is a generic term for
the classes of information created to describe
(in technical language) the use, functionality
or architecture of a product, system or
service.’
- Wikipedia
 Technical documents: Some Samples
• Patent documents
• Specifications of components/products
• Data sheets of item or of components
• Testing methods
• Manufacturing standards
• System requirements
• System architecture
 Technical Documentation [TD]
• Generally, technical documentation lack
universal standards in terms of their format,
content and structure.
• Standards developed by: International
Organization for Standardization (ISO).
• Prescribe standards for the preparation
technical documentation like: user guides,
manuals, product specifications, etc.
 5 Steps to Create Technical Documentation

• Man has invented tools for the aid of the

humanity.
• Others need help in using the tool and only
through language the instruction on how to use it.
• Thus came the technical documentation.
• The first example of technical writing in English:
Middle Ages - Poet Chaucer wrote a guide to the
Astrolabe—a device used for measuring the
distance of stars.
 Technical documentation

• TD: any document that explains the use,

functionality, creation, or architecture of a
product.
• Think of it as a nuts-and-bolts “how to” guide for
your users, new hires, administrators, and anyone
else who needs to know how your product works.
• Technical documentation isn’t just about
capturing information.
• It’s about presenting it in a way that’s easy to
read, usable, and actually helpful for your
audience.
 When, why, and how to properly use
technical documentation

• TD helps an intended audience use your

product, understand your processes, and not
get stuck.
• Audience: end-users, administrators,
colleagues, or technicians
• TD muse be:
clear, searchable, and helpful for them.
 When, why, and how to properly use
technical documentation…
• Great technical documentation empowers your
users, not frustrates them.
• It’s an integral part of not just customer
support, but brand building and trust.
• Users seek it out when they’re most in need.
• If it’s not available, they’ll start looking for
alternatives.
 Examples of where and how
you can use technical documentation
• End-user support: This means things like user
guides, release notes, online help systems,
training programs, or operating
procedures—anything that helps customers to
use your product.
• Marketing support: Anything that’s
product-focused and used to market your
company (like explainer videos, presentation,
or technical landing pages)
 Where and how you can use…

• Development support: This could be functional

and technical specifications, software
development guides, or simply procedures and
tools to help your developers do their jobs.
• Organization support: Information about your
company, structure, procedures, workflows,
policies, and anything else teammates need to
know to do their jobs.
 TD…
• Most of these documents would come as
physical guides for users and they must be
available on your website or help pages.
Who makes TD:
• Usually written by a subject matter expert or a
technical writer who’s been trained to translate
complicated product knowledge into content
that’s more easily understood by the end users.
 Steps for developing TD

Once you’ve put your team together,

writing technical documents comes
down to a few simple steps.
 Step 1: Do research and create a
“Documentation Plan”
• a prior preparation and research
• Knowing the purpose and scope of your technical
documentation - saves much of your time and energy
• If you’re not the subject matter expert, you may have
interviews and discussions with the technical team to get
a stronger grasp on the material.
• “Mission Impossible.”
• follow the principles of the pre-writing process.
• Go through the existing resources and guides and do a
short audit of what you have and what’s missing.
• This sort of preparation is what is called ‘a documentation
plan.’ - a short outline
 Documentation plan should have:

1. Goals: Having and knowing a clear goal is

essential to writing good technical documentation
2. Existing resources: Check the existing resources.
Are you updating or merging current resources or
starting from scratch? Do you want to replace the
old, outdated versions? Do a quick check and find
everything that will help you write the document.
 Documentation plan should have:

3. Style guides: Some industries require you to write

technical documentation in a specific way.
• Government departments - plain language.
• Aerospace, aviation, or defense companies -
simplified technical English
• Follow the style guide prescribed by a company.
• A style guide: what language to use, how to talk to
users, and even grammatical styles.
 Documentation plan should have:
4. Outline of topics:
• topics and subtopics
• Outline as a ‘Table of Contents;’ list out every major
section and subsection
5. Tools and management:
Decide the software, tools, or websites that will be
used to create and manage the documentation.
6. Deadline and final deliverables:
• Check the due date and format
• Know the content that is to be presented; to
understand what you need and where to put your
efforts.
Documentation Development Life Cycle
(DDCL)
Source: Technical writer for IT Infrastructure
 Step 2: Structure and design
• The objective of any technical documentation is its
‘usability.’
• structurally logical and easy to navigate; think about
how that content is going to be presented.
Think about:
• On page design [layout] (how the individual technical
documents look, what’s included in them, and the
hierarchy of information)
• The navigational structure of your document (what
order is information presented in, how do users
move around and navigate, what documents are
linked or connected, etc...)
 i. On-Page design
Use a template or schema
(a blueprint of how your data will be constructed)
__________________________________________
TD template may look like this:
• Title: What is it?
• Subtitle: Additional information
• Overview: What will you learn
• Table of contents: Internal navigation
• Features: Each section of the document
• Read next: Related documents that might help the user
 ii. Logical navigation structure

• organized in a way that makes sense and can

be quickly parsed
• What are the main topics that people will be
searching for? Under each of those, what
specific questions or documents will they be
looking for?
• address these issues when you write the
document.
 Step 3: Create the content
• With your documentation
plan and structure in place, it’s time to get
serious about creating the technical
document.
• Like any writing project, the easiest way to
create technical documentation is to follow a
few steps.
 Ways to make create
useful, valuable, and clear documents
Start with a draft
• sketch out a high-level outline for each of the topics
• to find gaps in your planning and research.
• gather the rest of the specific content you’ll need
• If you are writing a help guide, you should follow
along and do a self-review to make sure everything
you’re writing can be done.
• your technical documentation is for the user.
• If they can’t easily navigate, read, and use what
you’re creating, it’s useless.
 A few quick tips on writing well:
• Write like a human: Use simple, clear language
whenever possible.
• Remember, your readers aren’t you: The golden
commandment of technical writing is thou shalt not
assume. Don’t assume they know even half as much as
you.
• Write as much as needed to be helpful and not a word
more: Short writing is good writing.
• “A good technical writer reduces the word count to just
the right brevity without being obscure.”
- Amazon technical writer Tom Johnson
• Remember the power of visuals: Pictures really do say
a thousand words; visualize what you’re saying rather
than try to explain it.
 Quick steps…

• get feedback to ensure you’re explaining things

properly.
• have a subject matter expert (SME) final draft to
review.
• When you complete 30% of your document ask the
reviewer to engage in the broader outline, flow, and
structure of the document.
• While at 90% done you may ask them to go over the
documentation with a fine-tooth comb and criticize
any issues.
• have a steady schedule of reviews to avoid any
surprises at the end.
Get peer reviews and make revisions

• In between reviews you’ll also want to set up

peer-review sessions to make sure the
content is accessible and usable to your
intended audience.
• Ask a project stakeholder or someone outside
the project to go over your documents and
pick out anywhere they get lost or confused.
 Edit, Edit, Edit
• Good writing comes down to editing.
• With your feedback and revisions in place, edit
the documentation yourself or take it to a
technical editor who can make sure the
language has a logical flow and is consistent
throughout.
• Whenever possible, you should try to get a
second set of eyes on your content.
 Step 4: Deliver and Test

• get some real-world feedback on it.

• this step often gets skipped for want of time and
resources; think it’s not worth.
• TD is all about the user; if it doesn’t work for them,
it’s a failure and waste.
• Start with a simple safety check.
• Go through any documents, directions, or use cases
that could potentially cause someone’s computer
harm if done improperly.
• revisit the topics on ‘basic functionality’ and ‘terms
explained’ as these are the core of your documents
and should be precise.
 Deliver and Test…

• do a navigation audit.
• document structure is the key factor.
• If users can’t get around them easily they’re
just as useless.
• Check for broken links and make sure
navigational elements are working and
obvious (if you don’t have any, you’ll probably
want to add some).
 Deliver and Test…
• check for usability or UX (User eXperience) issues.
• Are users getting lost or confused?
• Are they not getting the answers they were looking
for (or thought they were getting based on
headlines or navigation?)
• The experience for the user comes down to more
than just what you’ve written.
• Take the time to work with outside testers to make
sure that when real users come to your documents,
they leave happy.
 Step 5: Create Maintenance and Update Schedule

• Now, you’re ready to push your

documentation out into the world. But if you
think your job is finished, think again.
• TD is living content that needs to be reviewed
and brought up-to-date with new product
releases or updates.
• Create a schedule for regular maintenance (go
through the test phases again) and updates.
 The Additional Qualities of Great Technical
Documentation

• Efficiency in development and use: Duplicated

content, unorganized structures, and unclear
processes can kill technical documentation.
• Up-to-date information: There’s no point in giving
your users inaccurate information. Keep your technical
documentation up-to-date and current.
• Consistent design and structure: Keep consistent with
your design, style, and tone across all online
documentation.
• Accessible anywhere: Your technical documentation,
just like the rest of your website or app, needs to be
responsive and provide a great experience for users on
all devices.
 Conclusion
Technical documents can empower or frustrate
It’s easy to downplay the role technical documentation plays in
your company’s success.

The easier it is for a user to find the information they need

to use your product, the more they’re going to enjoy it

They will stay loyal to your brand, and recommend you to

other people.

Take the time to follow the guidelines for technical

documentation and create a clear, accurate structure, and write
the content that gives your users a pleasant and enjoyable
experience.