using journalistic principles to improve user assistance

Using Journalistic Principles toUsing Journalistic Principles to Improve User Assistance

Ni k Bl i lNicky BleielSenior Information DeveloperComponentOnetcworld conference 2008tcworld conference 20085 November, 2008

What we’ll discussWhat we ll discuss• Writing Principlesg p• Gathering Information• Time Managementg• Convergence Technical Communication• Commonalities

Writing PrinciplesWriting Principles1. Inverted Pyramidy2. Don’t Bury the Lead3. 5 W’s

All work together –using #1 guaranteesusing #1 guarantees

you don’t do #2 and use #3use #3

Writing Principles

1. Inverted PyramidyMost 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 Principles2. 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.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” theLead can be followed by a 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 picking up the p g ppaper.

Most important information goes hereMost important information goes here.

• … has web equivalent “Above the scroll”… has web equivalent Above the scroll

Part of the page user can see without scrolling ddown.

Writing PrinciplesWriting PrinciplesThe 5 WsThe 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 and Who.yI send them over land and sea,I send them east and west; But after they have worked for meBut after they have worked for me, I give them all a rest. – From "The Elephant's Child" by Rudyard Kipling

Writing PrinciplesWriting Principles3. The 5 Ws

• What are we trying to accomplish?• What happened? • Who was there?

?

• What are we trying to accomplish? (feature description, overview, etc.)

• Who can make it happen?• Why should they make it happen?• Where did it happen?

• When did it happen?• Why did it happen?

Why should they make it happen?• Where (in the UI) will it happen? • When will it happen? (conditions)• How do you make it happen? (steps)• Why did it happen?

• How did it happen?

y pp ( p )

Ask these questions when conducting interviews …

Gathering InformationGathering Information• Interviewing skills … or Working with Subject g g j

Matter Experts— Find the right person (or people)

C b t i f ti— Corroborate information— Be assertive

Be prepared to throw out unusable information— Be prepared to throw out unusable information

Gathering InformationGathering Information

• “Beat” can be an area of expertise or a responsibility

E i– Economics– Medicine– City government– City government– Local sports team

Product is a TC’s “beat”

Gathering InformationGathering Information

R h• Research— Background/fact-checking

I t i— Interviews— Library— WebWeb

Time ManagementTime Management• Deadlines!

— A line which does not move.

A guideline marked on a plate for a printing press (inside which all content should appear)(inside which all content should appear).

Courtesy Wiktionary.org

CommonalitiesCommonalities

Con ergence ith Web 2 0Convergence with Web 2.0• Convergence Journalism • Convergence Technical Communication• Convergence Technical Communication

Convergence with Web 2.0Convergence with Web 2.0Both have …• Multiple Deliverables

• Video• Podcasts• Blogs

• User Participation• User Participation• Comments• Wikis• Wikis

• Continuous Publishing model

CommonalitiesCommonalities

• Knowing the Audience• Interests• Skill levels• Community

CommonalitiesStyle 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.

CommonalitiesCommonalities• Knowledge Managementg g

• Internal KM methodologies are important so that important information can be found, retrieved

and reused… and reused.

CommonalitiesCommonalities• Loss of formatting controlg

• Journalists gave this up long ago.• With single-sourcing, modular writing, content

management, this is becoming much more common for tech comms.

CommonalitiesCommonalitiesThe “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 Readingg

BooksConvergence Journalism: Writing and

Reporting Across the News Media by J. KolodzyKolodzy

The Wisdom of Crowds by J. Surowieckiy

Smart Mobs by Howard Rheingold

On Writing Well: The Classic Guide to Writing Nonfiction by W.K. ZinsserNonfiction by W.K. Zinsser

Further ReadingFurther ReadingOn the WebJournalism.org: Project for Excellence in

Journalismhttp://www.journalism.org/resources

The Committee for Concerned Journalists “JThe Committee for Concerned Journalists “J-Tools”

http://www.concernedjournalists.org/tools/index

Participatory Media Guidebook http://pmguide wetpaint com/http://pmguide.wetpaint.com/

Further ReadingFurther ReadingPoynter Onlineyhttp://www.poynter.org/

Th Lit t N t kThe Literature Networkhttp://www.online-literature.com/kipling/165/

Communication, Cultural and Media Studies (CCMS) infobase

http://www.cultsock.ndirect.co.uk/MUHome/cshtml/index.html

QuestionsContact information:Ni k Bl i lNicky BleielComponentOnePittsburgh, PAnickyb@componentone comnickyb@componentone.comwww.componentone.com

Blog “Technical Communication Camp”Blog Technical Communication 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 deliverablesinterview-with-nicky-bleiel/