Writing Strategy

I-Writing Strategy Checklist: Questions to Ask

Writer Strategy
1. What is my objective? (You should be able to say “As a
result of this document, my readers will . . . .”)
2. What style is best for my context: Informal, formal,
professional jargon?

1
3. What is my credibility: Position in hierarchy, expertise,
relation to audience?

Analysis of Readers
1. Who is my audience: Professor, supervisor, peers, employees?
2. How can I analyze them: As individuals, as a group?
3. What do they know: Necessary background information, new
information, expectations for style and format?
4. What do they feel: Interest level, bias, ease or difficulty?

Message Strategy
2
1. Should I be direct or indirect?
2. How can I organize a strategic message?
3. What document format is most appropriate: E-mail, letter,
brief, memo, short report, formal report?

3
Cultural Strategy
1. How does culture affect my strategy: Objective, style,
credibility? What adjustments do I need to make to be
reader-friendly?

4
2. International Style Guidelines
In professional writing, the term “good style” refers to a way of
writing that allows the audience to read with speed and clarity.
The “pleasure of the text” is not a concern in this context. We
can increase the ease with which all audiences (including
international audiences) read our documents quickly and
accurately by following these guidelines.

5
 Use short sentences to minimize the chance of
misunderstanding.
 Use topic sentences at the start of paragraphs.
 Avoid informal style, jargon and humor.
 Avoid acronyms except for specialist audiences.
 Use frequent transition phrases.
 Use metaphors, similes and analogies carefully.
 Use clear and complete headings and captions.

6
Technical documentation refers to any document that explains
the use, functionality, creation, or architecture of a product,
software application, or process. This documentation is
necessary in almost all workplaces to turn specialized technical
information into content that is easier for readers to understand.
By helping users perform a task, technical
documentation serves to facilitate the communication with both
internal (employees) and external customers that is vital for
business success.
7
3-Users of technical writing
A variety of users can benefit from good technical
documentation to help with performance of daily tasks:

 External customers – User guides, release notes, online

help systems, training programs.
 IT – Product manuals, system and information architecture
manuals, for system administrators.
8
 Internal customers – SOPs, workflows, company policies,
company structure, proposals.
 Developers – Functional and technical specifications,
software development guides.
 Marketing – Presentations, web content, white papers.

9
4-Benefits of good technical documentation:
 Reduced training time and costs – With good
documentation, new hires can quickly and easily learn
about the processes and software systems that they will use
without costing your existing staff time and effort. These
benefits often translate into a favorable ROI (Return Of
Investment).

10
 Enhanced operational efficiency – Good documentation
provides an easy reference for employees and thus helps to
ensure that all of your company’s processes are running as
consistently and efficiently as they can be. Operational
efficiency is usually enhanced if the technical writers are
using a component content management system.

11
 Improved outsourcing – If you decide to outsource parts
of your business, good documentation (e.g., SOPs, training
programs, etc.) helps all of your outsourced employees
know what they are doing and what is expected of them.

 Builds company value – Well documented processes and

hardware/software systems are of enormous value to a
potential buyer of the company. As such, good
12
 documentation is a tangible asset that can increase a
company’s future share value and sale price.

 Improved regulatory compliance – For companies

operating in regulated environments (e.g., GxP), good
documentation practice (GDP) is required by regulatory
agencies. Good technical documentation meets regulatory
compliance standards and provides required consistency.
13
 Efficient system upgrades, maintenance,
troubleshooting, and validation – Good technical
documentation dramatically improves the efficiency of
software system upgrade, maintenance, troubleshooting,
and validation activities.

14
 Increased sales – Salespeople can improve their
performance dramatically when they have good marketing
collateral such as white papers to share with potential
clients.

15
We discuss the different types of users that technical
documentation supports, along with the ways in which good
technical writing can benefit your business as a whole:

 Reduced training time and costs

 Enhanced operational efficiency
 Improved outsourcing
 Increased company value
 Improved regulatory compliance
 Increased sales
 More efficient system upgrades and troubleshooting

16
In order to capitalize on these benefits, it is often helpful for
organizations to undergo a bit of a shift in the way they view
technical documentation. All too often, company executives,
managers and/or developers see documentation as just a
necessary evil – something that needs to get done because
customers or regulatory agencies expect it. This can lead to a
scenario where engineers and/or developers quickly put
together documentation at the end of the project just before
product launch.
17
In today’s highly competitive business environment,
documentation neglect is not a winning strategy. Leading
organizations have made a paradigm shift in this regard and
view technical documentation as a critical project deliverable
that is an essential part of good product development. Indeed,
even in the digital age, a good user guide for a software
application can be a vital part of what makes or breaks
successful user adoption.

18
Like any other project deliverable or product, technical
documentation needs to be planned, created, delivered, and
managed in a way that intersects the needs of users with the
needs of the business.

The bottom line: Organizations should follow a best practice

approach to ensure their documentation takes care of the people
(users) that take care of them.

19
5-Best Practices for Creating Effective Technical
Documentation: General Methodology
Writing and releasing effective technical documentation
requires a best practice methodology to ensure the maximum
benefits for your organization. Key steps of this methodology
include:

20
 a-Choose the right documentation type.
The different types of technical documentation are virtually
endless – user manuals, how to guides, reviews, reports,
newsletters, presentations, web pages, proposals, fliers, memos,
21
press releases, handbooks, installation guides, FAQs, release
notes, help files, SOP documents, API documentation, style
guides, user requirements specification, etc. One of the first
things a technical writer needs to do is determine which type of
document is most appropriate to meet the customer’s needs. A
thorough audience assessment and task analysis is essential for
this purpose.

22
 b-Create a documentation plan.
The first step in any documentation project should be to create a
plan that serves to align all technical documentation with the
needs of the organization. Technical writers will need to
interview company stakeholders, including product manager,
QA, Legal, and Subject Matter Experts (SMEs), to gather the
information necessary to begin the plan. The documentation

23
plan is typically introduced to the team during a kickoff
meeting.

A document plan should include the following:

 Purpose and objectives–

What is the intended purpose of the documentation? What

problems will the documents be solving? What will readers
of the documentation be using it to accomplish?

24
 Audience – Who are you writing for? What are the user’s
needs? At which point in daily job performance will users
likely need the content? These questions should be
answered for both current and potential future users.
Technical writers will want to know as many relevant
details of the intended audience as possible – age, education
level, job title(s), job function, learning styles, technical
expertise, skills, etc. In gathering information, technical
writers will typically want to talk to either actual users or
25
 people who are interacting with the company’s userbase
(e.g., salespeople, account managers, customer service,
etc.).
 List of deliverables – What documents will the team write?
What are their IDs according to the repository used to store
them? What is the status of each deliverable?
 Team – Who are the team members and their roles? Who
will be reviewing and/or approving the documentation?
Who are the backups?
26
 Existing resources – What documentation is currently out
there? Will you be starting from scratch or simply merging
current resources? Are there old, outdated versions of the
documentation that will need to be removed from
circulation? Where are the voice-of-the-customer transcripts
to define requirements? Technical writers will want to
conduct a thorough audit to find out what documentation is
currently out there that will either help them write or
confuse the audience if they find it.
27
  Choose the right authoring tool.

One of the most challenging aspects of becoming a good

technical writer is learning how to use all the different authoring
tools available. The technical writer must be strongly competent
in many different authoring tools, because organizations will
likely require the writer to use whatever tool is available.
Authoring tools generally fall into one of five different
categories:

28
*Desktop publishing – Standalone systems that live on
PCs and allow technical writers to both author and publish;
for example, Google Docs, Microsoft® Word®, Adobe®
FrameMaker®, Adobe® RoboHelp®, Adobe® InDesign®.
These tools are good for small teams and content that is not
reused or published to multiple outputs.

*Structured authoring – These types of tools are basically

text editors that can be used with a markup language live
XML or DITA to tag content based on predefined set of
29
rules (e.g., document type definition or DTD). Examples
include Adobe FrameMaker, oXygen, XMetaL and
ArborText. Structured authoring tools are good for larger
teams creating content that will be reused and/or published
to multiple outlets. Structured authoring is used in content
management systems (CMSs) such as MadCap® Flare and
Tridion products. CMSs are particularly valued for their
XML output that is used by translation services.

30
*Help authoring tools (HATs) – These tools are designed
to deliver online help to users. Some HATs like RoboHelp
can also do desktop publishing. HAT tools are good for
small teams and content that does not need to be translated
or managed within the tool.

*API and developer documentation – API documentation

is a rapidly growing niche within the technical writing
profession, as many companies are finding that technical
writers are better at creating this kind of documentation
31
than software developers. Examples include Sphinx,
Swagger, Slate, and Jekyll.

*All-in-one tools – these tools combine authoring,

publishing and content management into a single tool such
as Author-it, IXIASOFT, easyDITA. Good for large teams
and medium-sized teams that lack large budgets or
technical resources.

*Authoring and software tools –

32
What software tools, software, and/or websites will be used
to create and manage the documentation? Gone are the days
when Microsoft Word was the only tool used for technical
documentation. Technical writing today encompasses not
just written text, but also demo videos, interactive media,
online Wiki pages, and much more. New authoring tools,
including content management systems, are replacing
traditional authoring tools, making it easier for technical
writers to assemble task-oriented topic-based deliverables.
33
 It is important for a technical writer to be well-versed in the
different tools/software for technical writing that have
emerged in order to choose the most appropriate tool(s) for
the job.

 Style guides – Does the company have a style guide that

details what grammatical styles, fonts, languages to use for
technical documentation? Are there specific mandates on
how to talk to users? Also, some industries require technical
documentation to be written in a specific way (e.g.,
34
 Simplified Technical English for aerospace, aviation and
defense companies).

 Outline – Technical documentation is as much about

structure and presentation as it is content. No matter how
good the information is, if it is not formatted well it can be
difficult to use. As such, effective technical documentation
is carefully planned and organized. Technical writers
35
 should create a table of contents for each technical
document they are writing that lists out the hierarchy of
information (i.e., topics and subtopics) that will be
presented. The outline should be a simple and logical
structure that supports reader comprehension, is
consistent across documents, and makes your
documents easy to navigate and search.
 Schedule – What are the milestones and deadlines to
complete each deliverable? How many review cycles will
36
 you schedule for each? The number of review cycles
typically range from two to three.

 Task analysis and Scope of Writing

– A task analysis determines which tasks are performed by

users, along with key steps involved in completing those
tasks. This information will help identify which tasks need
to be documented, along with which type of document is
37
 most appropriate for this purpose. A task analysis is critical
to create an outline for a deliverable or develop a set of
online help topics. In addition, a thorough task analysis can
help project managers define project scope.

 Be brief, yet thorough. After identifying users and tasks,

practicing minimalism is perhaps the most important
criterion for good technical writing. While fulfilling safety,
38
compliance, and legal requirements, technical documents
should contain only as much content as required for the user
to perform a task, and not a word more. Readers of
technical documents are typically busy people, and they
expect documentation without repetitiveness, wordiness or
redundancies. Give the audience the information when and
where they need it. If necessary, appendices can provide
supplementary material. Minimalist technical writing saves
time and money.
39
 c-Foster efficiency by topic-based
authoring. Topic-based technical writing is a modular
approach to creating content that is structured around topics,
where each “topic” has an identifiable purpose (procedure,
concept, reference) that does not require external context to
understand. This type of authoring fosters efficiency in
technical writing, as it allows the different modules to be mixed
and reused in different contexts. Topic-based writing can
40
streamline content, as minimalism dictates. Topics are also the
backbone of component content management systems, where
technical writers assemble topics into documents.

d-Practice task-oriented technical writing.

Technical documentation helps the user perform a task that
accomplishes real-world goals. As such, task-oriented writing
that provides a workflow to do something is preferred over
41
writing with a functional orientation. For technical writers,
writing with a functional orientation (for example,
systematically explaining each function, feature, or interface
element of a product) is only appropriate in functional
specifications and some SOPs. Functional writing can be a
burden to the user. Every good technical writer is proficient at
writing task-oriented topics.

Task-oriented writing requires a comprehensive task analysis

prior to the start of the writing. Technical writers or marketing
42
staff should interview users and observe what they do, an
activity called contextual inquiry. Tasks can be discovered by
reviewing voice-of-the-customer material from marketing and
customer logs from technical support. After the tasks and
workflows are defined, technical writers can then develop the
documentation.

e-Use templates for consistent on-page design.

43
Templates lock in structure and consistency. They are a good
tool to plan documentation. For example, a template for a
single-chapter protocol contains headings and boilerplate text:

 Title and document part number – What the document is

about and how it is referenced including version number
and date.
 Before you begin – Prerequisites to complete before
performing a task.

44
 Materials required – All items needed to complete the
task, usually tabulated with part numbers.
 Step-wise procedure – Numbered steps in a workflow. The
steps also include notes. Notes format are included in the
template.
 Graphics – Formats for diagrams, photographs, and tables
to support the text.
 Read next – Related documents that the user may find
useful.
45
 f-Use visuals.
Whenever possible, use pictures, diagrams, graphics, tables, and
bulleted lists to visualize the content. Show, not tell. In addition
to being an effective way to communicate information, visuals
will help improve the readability of documentation by breaking
up the monotony, length, and complexity of the text. The
principle of minimalism applies to visuals for maximum impact
and meaning.

g-Use examples.
46
When trying to make a concept crystal clear, first verbally
describe the concept, then add a visual illustration, and finally
provide an example of the concept. Let’s apply this tip to an
elementary algebraic concept.

47
 h- Align on a review schedule.
Writing is a cyclical process, and good technical writing
requires concepts, processes, and terminology to be clarified
and honed over time. Unless the technical writer is an expert in
the topic, timely feedback from subject matter experts will be
essential as the process proceeds.

A review schedule should be created with key SMEs to help

improve the value and accuracy of the document as it is being
written. At minimum, SMEs should review and provide
48
feedback on the initial outline for the documentation, at least
one draft in progress, and the final draft. The initial review will
provide feedback on the broader outline, flow and structure of
the document, while the review of an intermediate draft and
final draft will provide thorough feedback on the content.
Ideally, one SME will serve as the single point-of-contact for a
group of SMEs to curate comments before marking up the draft.

In between reviews by SMEs, it can be helpful to have a

colleague or project stakeholder review the document to help
49
catch any typos or grammatical issues, check that the links and
other navigational elements work, and make sure the concepts
discussed are easily understandable. The more feedback is
collected from different readers and perspectives, the more
accurate and readable the document will become.

Pro tip: Do not hesitate to schedule writing sessions to resolve

edits among SMEs. Circulating a PDF and asking for comments
on a few remaining issues is most effective towards final
completion of a deliverable.
50
 i-Create a document release protocol.
A protocol should be developed for final document approval
and release. This should involve the proper company
stakeholders and will need to be coordinated with the
company’s quality department in regulated industries.

j-Manage the project.

51
Documentation projects can involve many different
stakeholders located around the world for global organizations.
There are a lot of moving pieces to a successful documentation
project.

 SMEs must be interviewed to gather information and

sometimes trained to assist with the writing.
 Documentation needs to be managed properly (e.g., version
control, user access, etc.) within the software and/or
websites where it is housed as it is developed.
52
 Effective communication must be facilitated between all
parties involved in creating, reviewing, and releasing
documentation. This can involve navigating language
barriers in multi-site, global organizations. Do not estimate
the impact of different time zones on team productivity and
impact on tight deadlines.
 The review and document release processes must be
coordinated and managed. Under cGxP, release processes
must be traceable to review the entire document history.
53
The best technical writers have the skills to coordinate all these
activities and effectively manage the documentation project.

k-Create an update schedule.

The job of a technical writer is not done when a finalized
document is released and delivered. Documentation can go out
of date very quickly as products, processes and software
systems change over time. Technical documentation is living
54
content that needs to be kept up-to-date and current with new
product releases, upgrades, and process changes. As such,
technical writers should create a schedule for regular review
and updates on all documentation they deliver.

55
Conclusion

Technical documentation plays an important role in your

company’s success by giving people the information they need
to perform tasks successfully. Technical documentation should
never be viewed as just another task to be completed, but
instead as an essential part of supporting the people that support
you.

56