(Thanks to Craig Jackson for taking these notes!)

Writing Documentation, Dena Strong

Friday, July 08, 2011

9:01 AM

Best Line: “People don’t want to read a doc, they want to find information” (Specifically, they want to know how to accomplish something. -Dena)

Idea started at IT Pro Forum session on training

• Most requested topic was writing documentation users will read
• Keeping “awesome” for search purposes … 😉
  

How to write fast and good

Had a real-life lesson on college when her English prof asked her how her paper was coming along…and it was due in 2 hours. She did get a 10-page paper on Milton completed on time. (I also got an A on it! -Dena)

Lesson: Write for your professor, e.g., write to your target audience

All of the Writing Awesome Documentation info is on the wiki

• Will be putting templates on the wiki

o    Software installation

o    FAQ’s

o    Status reports

• The more templates we can put together (share, edit) the better for all

o    Dena doesn’t get writer’s block as she utilizes templates so knows how to start a document

o    Templates & outlines are also useful, particularly for meeting accessibility guidelines

o    Outlines and think about how to provide breaks, links, etc to make the doc easy to find information from the user’s perspective

“People don’t want to read a doc, they want to find information”

Do need internal and external documentation — know your user bases

• Might need more than two versions of the documentation so that it is useful for all of your audiences
  

Speed Writing

• Start with outlines
• Know your persona (gamer perspective) for writing the documentation

o    Think about your docs being used by your grandmother

• Would it make sense to her?
• Grandma wants every step written down

o    Take screen shots and number them so you keep the correct order

• Windows 7 built-in facility for a running screen capture
• Need to catch it the first time as some stuff never un-installs so will be different the next time you go through the process
• Standard format

o    Page summary

o    Who can use it

o    Getting Started

o    Actually Using It

o    How to fix

o    Next Audience: IT Pro entry point

• How to get the “widget”
• System requirements / Tech specs
• Tools for them to provide support to their users
• How they can get support themselves from the service provider

§  Okay to go all techy at this point as the audience is technical

• IT Pros are in the middle
• They are consumers as well as service providers

§  Once name something and publish it, do NOT rename it

§  Make sure words count

• “Click Here” when there is a link
• Be specific
• Keep paragraphs short
• If more than 4 lines, break it up

o    Find an end-user to go through your documentation

• Watch what they do
• Do NOT tell them anything; have to follow their process

§  Might need to have someone else do this if you are too helpful

• If a user gets stuck, there is a problem with either the documentation or the service
• Please let the user/tester know that they are not going to be judged, they are a crucial part of the learning process so that calls to help desk/IT Pros will be reduced or won’t happen
  

Q&A and comments

• Use third-party documentation if it is good (vendor, other campus, etc)

o    No need to re-write someone else’s good documentation

• MS’s Lync (UC) documentation is really good — docs and videos
• Good news about web documentation is that you can add/edit/delete based on user experiences