Scribd
Upload
207 views66 pages

2 Technical Writing Software Documentation m2 Slides PDF

The document discusses the key phases of the writing process: Plan, Research, Write, Review/Edit, and Launch. In the Plan phase, the writer determines the purpose of the document, intended audience, and best delivery method. Research involves interviewing subject matter experts and reviewing existing documentation. The Write phase is about drafting the initial content. Review/Edit consists of revising, editing, and testing the document. Launch is finalizing and releasing the documentation.

Uploaded by

ancgate
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
207 views66 pages

2 Technical Writing Software Documentation m2 Slides PDF

The document discusses the key phases of the writing process: Plan, Research, Write, Review/Edit, and Launch. In the Plan phase, the writer determines the purpose of the document, intended audience, and best delivery method. Research involves interviewing subject matter experts and reviewing existing documentation. The Write phase is about drafting the initial content. Review/Edit consists of revising, editing, and testing the document. Launch is finalizing and releasing the documentation.

Uploaded by

ancgate
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 66

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

You might also like