why document? documentation is an integral part of the development cycle benefits users using the...
DESCRIPTION
Common types Tutorial –Takes user through, step-by-step –Often Web or video-based –How-to, job-aids Thematic/User Guides –Divided into chapters or sections –Books Reference –Alphabetical, cross referenced –Encyclopedias, searchable databases HTML code comments –Bring consistency to development and documentation efforts Source: WikipediaTRANSCRIPT
Why document?• Documentation is an integral part of the
development cycle
• Benefits users using the system
• Acts as resource for the helpdesk supporting system and users
• Potential mechanism to spread the word of new system
Common types• Tutorial
– Takes user through, step-by-step– Often Web or video-based– How-to, job-aids
• Thematic/User Guides– Divided into chapters or sections– Books
• Reference– Alphabetical, cross referenced– Encyclopedias, searchable databases
• HTML code comments– Bring consistency to development and documentation efforts
Source: Wikipedia
Example - Tutorial• http://help.breeze.msu.edu
Example - Thematichttp://www.nps.gov/nr/publications/bulletins/nrb16b/INDEX.htm
Example - Reference• http://www.wikipedia.org
Starting the process…
Identify your audience• For whom are you documenting?
• End users?• System administrators?• Non-technical people?• Technical people?• Training manuals?• All of the above?
Identify needs• Talk to the people who will be using your
system– What is most confusing?– What is the easiest?– What is their preferred delivery mechanism?
Source: techrepublic.com
• Survey the helpdesk, or those who answer questions– This will give an idea of frequently asked questions
Identify resources• How many people are available to work
on this?– Will you have student help available?– Ensure programmer/developer time will be available for
input and review
• How will these resources be coordinated and distributed?– Wiki– ANGEL group– Google docs (be careful)
• Check http://computing.msu.edu for Google safety article– Newsletter or publication
Five tips:making it easy
1 - Keep it Concise• Short sentences
– Limit segments of narrative text
2 - Keep it Clear• Use screen captures to illustrate
points– Nothing explains what the screen
should look like better than a picture• Jing Project by TechSmith
EBSPTweetPoke
Keep it Clear cont’d• Avoid unnecessary abbreviations and
jargon
– When using abbreviations, first explain what they mean
– Ex: EBSP – do people outside of Libraries, Computing and Technology know what “Eebeespeebee” means unless we tell them?
3 - Keep it Consistent• Don’t switch formats, naming conventions
and denotations– “Email,” “e-mail,” “email,” “E-Mail”– Mind your tenses
• If it’s documented once, document it throughout
4 - Keep it Updated• As features change, so should
documentation– How crucial is that last updated date?
• Review regularly and keep it timely– Focus groups– Integration into maintenance cycle– Students (with supervision)
• Create mechanisms for feedback
5 - Keep it Accessible• Help users find what they need
• Search functionality – http://help.msu.edu– http://help.angel.msu.edu
• Consider accessibility standards in the development process– http://webaccess.msu.edu/– http://usability.msu.edu/– http://rcpd.msu.edu
The good• http://www.akadia.com/services/ssh_test_certificate.html
– “I like this because it is clear in the formatting it is step-by-step yet the steps contain some explanatory text answers the Why? without going into too much detail and losing my attention.”
• http://www.apple.com/iwork/tutorials/#pages-create-0
– “In the category of video tutorials I particularly like those on the Apple site, not just because the videos are done well, but also the organization/navigation to the left.”
• http://www.visualjquery.com/
Questions? Comments?Discussion!
References List• http://www.techrepublic.com• http://www.wikipedia.com• http://www.techsmith.com• http://help.msu.edu• http://help.angel.msu.edu• http://www.apple.com• http://www.nps.gov/nr/publications/bulletins/nrb16b/INDEX.htm• http://www.twitter.com• http://www.facebook.com• http://ebsp.msu.edu
