The Writing Process
Amber Israelsen
DEVELOPER, AUTHOR, TRAINER
www.amberisraelsen.com
Course Outline
Introduction to The Writing Writing Tips Layout and Deliverables:
Technical Process and Best Design Requirements
Writing Practices
Deliverables: Deliverables: Deliverables: Deliverables: Conclusion and
Design/ Code Test Plans and End-User Additional
Architecture Documentation Test Cases Documentation Resources
CARL
Software Developer
I need you to write all
of the documentation.
Maybe Anne from the team
across the hall can give you
some pointers.
Later that day…
Hi Carl. Good to see you.
You too. Thanks for agreeing
to help with this. I’m not really
sure where to even start.
Well, you’re in luck.
I’ve done quite a bit of
technical writing so I
should be able to give
you some pointers.
Let’s start by talking
about the overall process.
The Writing Process
Plan Research Write Review/Edit Launch
Plan Research Write Review/Edit Launch
Plan Phase
Purpose Audience Delivery
Plan Phase
Purpose Audience Delivery
Purpose:
Why will the
document exist?
If a document doesn’t have
a purpose, it shouldn’t exist
Persuade readers to think or act a certain
way
Document Enable them to perform a task
Purposes Help them understand something
Change their attitude
What about your documents?
What’s the purpose?
Well, I have several…
Purpose of Software Documentation
Requirements Design/Architecture Code/Technical
Identify what is to be built, and Defines how the system will be Enable task completion and
to verify we’re meeting constructed, describing critical understanding
stakeholders’ expectations components and how they fit
together
Test Plans/Test Cases End-User
Define the approach to testing; Enable task completion;
expose errors or demonstrate provide support and
correct behavior troubleshooting
Plan Phase
Purpose Audience Delivery
Who will be reading it (demographics)?
What do they already know?
Why are they going to be reading it?
Analyzing Your In what environment will they be reading it?
Audience What is their state of mind?
ACK!
I just spilled hazardous waste!
What am I supposed to do?
Who will be reading it (demographics)?
What do they already know?
Why are they going to be reading it?
Analyzing Your In what environment will they be reading it?
Audience What is their state of mind?
What do they NEED to know?
What tone is appropriate?
Hi guys,
Welcome to the project! Here are the steps
to set up your development environment.
1. Download and install Visual Studio from
the file share
2. Connect to Team Foundation Server
1. Server name: pharmaTFS
2. Port: 8080
3. Do a “get” on the latest code base
4. Code up some awesomeness!
Let me know if you have any questions.
Amber
Writing Styles by Audience
Technical Level Description Users Writing Style
Non-Technical • Novice user • Sales & Marketing • Step-by-step
• No experience with • Prospective clients instructions
the product or • New team members • Definitions
concept • Full explanations and
details
Semi-Technical • Intermediate user • Sales & Marketing • Facts and figures
• Some experience with • Existing clients • Brief explanations
the product or • Developers • Moderate amount of
concept detail
Technical • Advanced user • Developers • Limited definitions
• Very experienced • System admins and amount of detail
with product or • Testers • Step-by-step
concept instructions not
necessary
What if I have more than
one audience?
PRIMARY SECONDARY
AUDIENCE AUDIENCE
Target reader May come into contact with the
Requested the document document
Often a decision maker But not the intended reader
You may have to create
multiple documents
Plan Phase
Purpose Audience Delivery
Delivery:
What’s the best way to
deliver the information to
the audience?
Here’s a fabulous online help
system you can use in the field.
Ummm…but we don’t have
reliable Internet service.
Good point. My audience will
be other developers, as well as
pharmacists and patients
getting their prescriptions.
The pharmacists are probably
busy and stressed out. And
the patients might not be
feeling well. Or they might be
elderly with poor eyesight.
Plan Research Write Review/Edit Launch
The Purpose of Technical Writing
Get information out …into the heads of
of the heads of the users in a way they
creators… can use it
Developers Users
The Purpose of Technical Writing
RESEARCH
Get information out …into the heads of
of the heads of the users in a way they
creators… can use it
Developers Users
RESEARCH
Interview Subject Matter Experts (SMEs)
Review Existing Documentation
Use the Software
RESEARCH
Interview Subject Matter Experts (SMEs)
Review Existing Documentation
Use the Software
Prepare interview questions
- Who, what, when, where, why, how
Preparing for - Open-ended
the SME - Each question should focus on one thing
Interview Anticipate possible directions of the
interview and think about your response
(i.e., how you will get back on track)
Decide if the interview will be recorded
- Get permission
Scheduling the Provide 2-3 timeslots of 60 minutes or less
SME Interview Communicate high-level topic areas
Schedule in a conference room to minimize
distractions
Start on time
Build rapport with small talk
Acknowledge expertise on both sides
State goals and topics of the interview
Be confident and relaxed
Conducting the Practice active listening
SME Interview Observe body language
Tune out distractions
Ask for additional thoughts before changing
topics
Review and confirm action items
Thank them for their time
For my project, I
already know a lot of
the information. But I
should talk to the rest
of the team as well.
I also need to look at
the documentation that
Justin started before he
left on sabbatical.
Great ideas!
Plan Research Write Review/Edit Launch
Get it on paper!
1
Organize your content and ideas
(e.g., chronological, parts of an object, simple to
complex, specific to general)
2 Write the first draft
3 Review and revise
Does the document fulfill its purpose?
Is anything missing?
Questions to Can anything be taken out?
Ask What questions will the reader have? And
answer them.
Is the writing easy to understand?
Sentence and paragraph structure
Grammar
Also Check:
Word choice
Spelling
Plan Research Write Review/Edit Launch
Adjust and reorganize content
Editing for style
Purpose
Editing for grammar and punctuation
Revise to incorporate test results
Tips for Reviewing and Editing
Walk away
Read out loud
Have someone Edit with a
else do it Print it knife
out/change
margins
Usability Testing
Line-by-line testing of a document to ensure it makes
sense and the instructions work as expected
Tips for Usability Testing
Have someone Test against a Observe the
else do it live system session
I think I’ll need to recruit
some reviewers and
testers. I’m probably
too close to everything.
That’s a great idea.
It’s always best to
have actual users
try it out.
Plan Research Write Review/Edit Launch
Ship it!
Handle translations, if applicable
Bundle up final deliverables (e.g.,
READMEs, web pages, PDFs, etc.)
Launch Coordinate with development team and
other writers to release (usually in
conjunction with software)
Create a plan for updates
Plan
- Purpose, Audience, Delivery
Research
Summary - Get the information out of the heads
of the creators
Write
- Get it on paper
Review/Edit
- Recruit others to help
- Usability testing is key
Launch!
Up next
