Using Journalistic Principles to

Improve User Assistance

Nicky
Ni k BlBleiel
i l
Senior Information Developer
ComponentOne
tcworld conference 2008
5 November, 2008
What we’ll
we ll discuss
• Writing
g Principles
p
• Gathering Information
• g
Time Management
• Convergence Technical Communication
• Commonalities
Writing Principles
1. Inverted Pyramid
y
2. Don’t Bury the Lead
3. 5 W’s

All work together –

using #1 guarantees
you don’t do #2 and
use #3
Writing Principles

1. Inverted Pyramid
y
Most important facts first, others following in
descending order

• For readers: Makes scanning easier

• For editors: Makes cutting easier (cut

information from bottom up)

• For TCs: Great way to plan and organize

From http://thesherpaproject.com/
Writing Principles
2. Don’t bury the lead (or lede)

“Burying the lead” is putting secondary

information at the beginning of a piece.
Effects the entire information structure.

Best practice to put the 5 W’s in the lead if

possible.

Lead can be followed by a “nut graph” — the 

nut graph the
“kernel” of information that informs the reader 
why they should care about this information.
Writing Principles
• Above the fold…

In newspapers, the top half of the page.

Reader can see it without p
pickingg up
p the
paper.

Most important information goes here.

here

• … has web equivalent “Above

Above the scroll
scroll”

Part of the page user can see without scrolling

down.
Writing Principles
The 5 Ws
I keep six honest serving-men:
(They taught me all I knew)
Their names are What and Where and When
And How and Why y and Who.
I send them over land and sea,
I send them east and west;
But after they have worked for me
me,
I give them all a rest.
– From "The Elephant's Child" by Rudyard Kipling
Writing Principles
3. The 5 Ws
• What are we trying to accomplish?
• What happened? (feature description, overview, etc.)
• Who was there? • Who can make it happen?
• Why should they make it happen?
• Where did it happen?
? • Where (in the UI) will it happen?
• When did it happen? • When will it happen? (conditions)
• How do y you make it happen?
pp ((steps)
p )
• Why did it happen?
• How did it happen?

Ask these questions when

conducting interviews …
Gathering Information
• Interviewing
g skills … or Working
g with Subject
j
Matter Experts
— Find the right person (or people)
— C
Corroborate
b t iinformation
f ti
— Be assertive
— Be prepared to throw out unusable information
Gathering Information
• “Beat” can be an area of expertise or a
responsibility
– Economics
E i
– Medicine
– City government
– Local sports team

Product is a TC’s “beat”

Gathering Information

• Research
R h
— Background/fact-checking
— I t i
Interviews
— Library
— Web
Time Management
• Deadlines!

— A line which does not move.

A guideline marked on a plate for a printing press

(inside which all content should appear)
appear).

Courtesy Wiktionary.org
Commonalities
Con ergence with
Convergence ith Web 2
2.0
0
• Convergence Journalism
• Convergence Technical Communication
Convergence with Web 2.0
Both have …
• Multiple Deliverables
• Video
• Podcasts
• Blogs
• User Participation
• Comments
• Wikis
• Continuous Publishing model
Commonalities
• Knowing the Audience
• Interests
• Skill levels
• Community
Commonalities
Style Guides
Commonalities
• Attribution
• Important to quote properly, give proper source credit
• With Web 2.0 comments, need to give credit for
suggestions/information in some way.
Commonalities
• Knowledge
g Management
g
• Internal KM methodologies are important so that
important information can be found, retrieved
… and reused
reused.
Commonalities
• Loss of formatting
g control
• Journalists gave this up long ago.
• With single-sourcing, modular writing, content
management, this is becoming much more common
for tech comms.
Commonalities
The “Fourth Estate”
• In Journalism, the “gatekeeper” or
“watchdog” role – defender and advocate.

In Tech Comm, writers often refer to

themselves as the “voice of the user.”
Further Reading
g
Books
Convergence Journalism: Writing and
Reporting Across the News Media by J.
Kolodzy

The Wisdom of Crowds by

y J. Surowiecki

Smart Mobs by Howard Rheingold

On Writing Well: The Classic Guide to Writing

Nonfiction by W.K. Zinsser
Further Reading
On the Web
Journalism.org: Project for Excellence in
Journalism
http://www.journalism.org/resources

The Committee for Concerned Journalists “J-

“J
Tools”
http://www.concernedjournalists.org/tools/index

Participatory Media Guidebook

http://pmguide wetpaint com/
http://pmguide.wetpaint.com/
Further Reading
Poynter
y Online
http://www.poynter.org/

The Literature
Th Lit t Network
N t k
http://www.online-literature.com/kipling/165/

Communication, Cultural and Media Studies

(CCMS) infobase
http://www.cultsock.ndirect.co.uk/MUHome/csh
tml/index.html
Questions
Contact information:
Ni k Bl
Nicky Bleiel
i l
ComponentOne
Pittsburgh, PA
nickyb@componentone com
nickyb@componentone.com
www.componentone.com

Blog “Technical
Technical Communication Camp
Camp”
http://blogs.componentone.com/CS/blogs/techcamp/default.aspx

Podcast on Tech Writer Voices/Interview with Tom Johnson

“Analyzing Your Users and Needs Before Creating Help
Deliverables”
http://www.idratherbewriting.com/2008/05/31/podcast-analyzing-
your users and needs before creating the help deliverables
your-users-and-needs-before-creating-the-help-deliverables-
interview-with-nicky-bleiel/