Day 7

Technical Writing Process

Warm-up exercise (20 min)
 Write instructions for doing something that can be done in the room
with available materials, such as tie a shoe, make a paper airplane, use
paper-clip, play a basic game like tic-tac-toe, and so on.
 Once completed, read your write-up loudly and note down areas where
your write-up can be improved.
Day 7: Technical writing process
Review process
Type of reviews
Review exercise
Review process
Reviews
 A review is an evaluation of a publication or any other deliverable
 Can be performed by an individual or by a team
 Can be internal (performed by other teams in the organization) or
external (performed by third-parties or customers)
 Can be triggered as part of the typical documentation development
process or as part of external requirements.
Why reviews?
 Ensure content scope and coverage is proper and is set at the right level
for the target audience
 Documents satisfies the explicit purposes or goals i.e. to provide
information, to give instructions, to persuade the reader, and to enact (or
prohibit) something.
 Document establish a relationship, create trust and credibility, and
provide accurate guidance to the user.
Review process
During After

Before
Follow-up
•Track action items and
issues
Resolve
•Assign responsibility
Review
•Facilitate meeting
Pre-review •Examine review
comments
•Self –review •Address issues
Familiarize •Prepare document for •Assess severity of issues
review •Identify action items
•Organize overview
meeting
Plan
•Identify participants
•Establish guidelines and
procedures
•Establish entry and exit
criteria
Before you start review
 Ensure that the document is in a state to be reviewed. The document
should not be incomplete or poorly written before sending for review.
 Identify your reviewers and inform them well in advance about the
review schedule.
 Scope the review: do you want reviewer to review the entire document
or certain sections? Do you want them review content for technical
accuracy, compliance requirements or language consistency?
 Set the expectations: Based on your viewpoint you can set the
expectations with the reviewer about the level of the review that you
expect them to perform.
Before you start review
 Set the acceptance criteria: Communicate clearly with the reviewer the
criteria to accept the review comments and marking review complete.
 Establish and follow deadlines: Set a realistic deadline for completing
the review and communicate to the reviewers. Consider the time
allocated for the review and see if it does not conflict with anything per
the project plan.
 Share checklists and guidelines: Make your reviewers aware of the
existing review guidelines and available checklists to ensure smooth
reviews.
Key reviews
Self review
 Process of reviewing your document yourself. This is typically done
before any other kind of review.
 Revise your document to produce a predictable and logical structure
between and within sections.
 A predictable and logical structure produces overall document
coherence, which allows your audience to read the document efficiently
and to use its information effectively.
 Consequently, the self review of any technical document should focus
on ensuring a logical and accessible structure.
Peer review
 Evaluation of work by one or more people of similar competence to the producers
of the work (peers).
 Often the first and sometimes the most useful step in the review process.
 Less formal and less threatening than managerial or technical reviews.
 Colleagues are often closer to the project than other types of reviewers, they can
often identify weaknesses in content and organization that other reviewers may
miss.
 Peer reviews of documents are a frequent and normal activity in most scientific
and technical organizations, with most engineers and scientists alternating between
the role of the individual requesting a review and that of the individual performing
it.
 Peer reviews are most useful when specific guidelines are followed in requesting
the review and the reviewer follows some important strategies in performing it.
Technical review
 The technical accuracy of a piece of writing should be the first level of review,
since it is a waste of time to work on a document that is wrong in content.
 Technical reviews are most often conducted by routing a document among
one's peers.
 A technical review may also be conducted by technical referees who are
experts in the relevant field.
 Technical review is concerned with one or more of the following questions:
 Is the problem addressed one that is technically important?
 Does the document solve the problem it sets out to solve?
 Are the methodology and general practice technically sound?
 Does the research lead to other important questions?
 Technical reviews are strictly matters of expertise
Editorial review
 Aim to improve the readability of a manuscript.
 Help examine the manuscript for ways in which it can be clarified and simplified.
 The editor either makes the changes and returns the marked-up manuscript to the writer
or makes marginal notes and a written report for the writer's use in revising.
 Editorial goals:
 Review the draft for content coverage and organization.
 Suggest adding or rearranging material, reordering paragraphs, or recasting sentences.
 Get a firm grasp of the author's purpose, problem statement, audience, and organization.
 Make marginal notes of sections that are vague, awkward, inconsistent, or poorly supported.
 Note any grammatical or stylistic problems as you read along.
 Place the problem in the context of the audience, the reader's purpose, and the rules of grammar and
style.
 Identify lack of clarity of purpose and problem, material inappropriate for a given audience, weak
organization, overall document organization, format inconsistencies, paragraph structure, grammatical
errors, stylistic weakness
 Read for punctuation and mechanics. Note patterns of misused punctuation, mechanics, and spelling,
as well as any misuse of units, acronyms, citations, or numbering of pages, sections, graphics, or
equations.
 Reference Link Text
Localization reviews
 Involves analyzing the semantics in the new language to make sure the right
thing is said, as well as making sure the products (functionally and linguistically)
in the intended culture.
 Localization review ensures that the product:
 Is appropriate for the target locale’s business and cultural conventions
 Appears custom built for the user’s cultural and linguistic background
 Does not change the original intended meaning
 Reviewers check a sample of files and look for errors in
 Accuracy
 Terminology
 Language quality (Truncations, display issues)
 Style guide
 Country standards
 Formatting
 Client-specific requirements
Managerial review
 View as a way organizations manage work and helps reshaping content
to fit organization’s objectives.
 The concerns of management may not be precisely aligned with those
of the staff.
 Management is focused on long-term issues, which include
administrative issues of cost, staffing, and work production. The staff, on
the other hand, is often focused on the short-term issues of the project.
 Helpful in getting individuals to focus their written work aligned with
organizational goals.
Usability review
 The objective is to identify specific concerns and goals the user might
face while using the documents for the product being developed.
 The documents could be very elaborate and testing the entire
document is not feasible.
 Choose 4 to 5 most critical tasks which are important from a user’s
perspective and where you think the user would likely refer to the
document while performing the task.
 Benchmark:
 Ability to complete tasks using instructions provided in the document
 Time taken to complete a task successfully while referring to the document
 No. of errors the users encounter while referring to the document
 Level of satisfaction while referring to the document
Review sign-offs
Review sign-offs
 Writers and reviewers work together as a team, review different parts
of the document, revise what needs to be changed, and then get it signed
off.
 Sign-offs ensure that all stakeholders agree to the document content
and it is complete from all aspect.
 Ensure that document is risk-free and does not contain any information
that may pose significant risks to the organization.
Exercise
Review exercise (20 min)
 Exchange the write-up that you have prepared as part of warm-up
exercise with your colleague.
 Review the write-up that you have received from your colleague and
make suggestions for improving the content.
 Return your review comments to the author.
 Does the comments you have received makes your document better? In
what manner?
Review exercise (45 minutes)
 Divide students into two groups
 First group to research and write a comparative analysis of Android-based
smartphones vs. Apple phones
 Second group to research and write a comparative analysis of Android-based
smartphones vs. Windows Phone
 Each group will select a representative to present the report they have
prepared, while members of the other group provide arguments to
counter the claims made by the other group.
 After presenting their cases, both groups will update their reports to
based on the feedbacks.
 Finally each group will present the key areas of improvements they
have identified as part of the review and how it helped them improve
their document.
Key takeaways
 Understanding the lifecycle of review process
 Understanding the scope and coverage of different types of reviews