Why document? Documentation is an integral part of the development cycle Benefits users using the...
-
Upload
lydia-skinner -
Category
Documents
-
view
214 -
download
0
description
Transcript of Why document? Documentation is an integral part of the development cycle Benefits users using the...
![Page 1: Why document? Documentation is an integral part of the development cycle Benefits users using the system Acts as resource for the helpdesk supporting.](https://reader035.fdocuments.net/reader035/viewer/2022062523/5a4d1b0d7f8b9ab05998c6f0/html5/thumbnails/1.jpg)
![Page 2: Why document? Documentation is an integral part of the development cycle Benefits users using the system Acts as resource for the helpdesk supporting.](https://reader035.fdocuments.net/reader035/viewer/2022062523/5a4d1b0d7f8b9ab05998c6f0/html5/thumbnails/2.jpg)
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
![Page 3: Why document? Documentation is an integral part of the development cycle Benefits users using the system Acts as resource for the helpdesk supporting.](https://reader035.fdocuments.net/reader035/viewer/2022062523/5a4d1b0d7f8b9ab05998c6f0/html5/thumbnails/3.jpg)
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
![Page 4: Why document? Documentation is an integral part of the development cycle Benefits users using the system Acts as resource for the helpdesk supporting.](https://reader035.fdocuments.net/reader035/viewer/2022062523/5a4d1b0d7f8b9ab05998c6f0/html5/thumbnails/4.jpg)
Example - Tutorial• http://help.breeze.msu.edu
![Page 5: Why document? Documentation is an integral part of the development cycle Benefits users using the system Acts as resource for the helpdesk supporting.](https://reader035.fdocuments.net/reader035/viewer/2022062523/5a4d1b0d7f8b9ab05998c6f0/html5/thumbnails/5.jpg)
Example - Thematichttp://www.nps.gov/nr/publications/bulletins/nrb16b/INDEX.htm
![Page 6: Why document? Documentation is an integral part of the development cycle Benefits users using the system Acts as resource for the helpdesk supporting.](https://reader035.fdocuments.net/reader035/viewer/2022062523/5a4d1b0d7f8b9ab05998c6f0/html5/thumbnails/6.jpg)
Example - Reference• http://www.wikipedia.org
![Page 7: Why document? Documentation is an integral part of the development cycle Benefits users using the system Acts as resource for the helpdesk supporting.](https://reader035.fdocuments.net/reader035/viewer/2022062523/5a4d1b0d7f8b9ab05998c6f0/html5/thumbnails/7.jpg)
Starting the process…
![Page 8: Why document? Documentation is an integral part of the development cycle Benefits users using the system Acts as resource for the helpdesk supporting.](https://reader035.fdocuments.net/reader035/viewer/2022062523/5a4d1b0d7f8b9ab05998c6f0/html5/thumbnails/8.jpg)
Identify your audience• For whom are you documenting?
• End users?• System administrators?• Non-technical people?• Technical people?• Training manuals?• All of the above?
![Page 9: Why document? Documentation is an integral part of the development cycle Benefits users using the system Acts as resource for the helpdesk supporting.](https://reader035.fdocuments.net/reader035/viewer/2022062523/5a4d1b0d7f8b9ab05998c6f0/html5/thumbnails/9.jpg)
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
![Page 10: Why document? Documentation is an integral part of the development cycle Benefits users using the system Acts as resource for the helpdesk supporting.](https://reader035.fdocuments.net/reader035/viewer/2022062523/5a4d1b0d7f8b9ab05998c6f0/html5/thumbnails/10.jpg)
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
![Page 11: Why document? Documentation is an integral part of the development cycle Benefits users using the system Acts as resource for the helpdesk supporting.](https://reader035.fdocuments.net/reader035/viewer/2022062523/5a4d1b0d7f8b9ab05998c6f0/html5/thumbnails/11.jpg)
Five tips:making it easy
![Page 12: Why document? Documentation is an integral part of the development cycle Benefits users using the system Acts as resource for the helpdesk supporting.](https://reader035.fdocuments.net/reader035/viewer/2022062523/5a4d1b0d7f8b9ab05998c6f0/html5/thumbnails/12.jpg)
1 - Keep it Concise• Short sentences
– Limit segments of narrative text
![Page 13: Why document? Documentation is an integral part of the development cycle Benefits users using the system Acts as resource for the helpdesk supporting.](https://reader035.fdocuments.net/reader035/viewer/2022062523/5a4d1b0d7f8b9ab05998c6f0/html5/thumbnails/13.jpg)
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
![Page 14: Why document? Documentation is an integral part of the development cycle Benefits users using the system Acts as resource for the helpdesk supporting.](https://reader035.fdocuments.net/reader035/viewer/2022062523/5a4d1b0d7f8b9ab05998c6f0/html5/thumbnails/14.jpg)
EBSPTweetPoke
![Page 15: Why document? Documentation is an integral part of the development cycle Benefits users using the system Acts as resource for the helpdesk supporting.](https://reader035.fdocuments.net/reader035/viewer/2022062523/5a4d1b0d7f8b9ab05998c6f0/html5/thumbnails/15.jpg)
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?
![Page 16: Why document? Documentation is an integral part of the development cycle Benefits users using the system Acts as resource for the helpdesk supporting.](https://reader035.fdocuments.net/reader035/viewer/2022062523/5a4d1b0d7f8b9ab05998c6f0/html5/thumbnails/16.jpg)
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
![Page 17: Why document? Documentation is an integral part of the development cycle Benefits users using the system Acts as resource for the helpdesk supporting.](https://reader035.fdocuments.net/reader035/viewer/2022062523/5a4d1b0d7f8b9ab05998c6f0/html5/thumbnails/17.jpg)
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
![Page 18: Why document? Documentation is an integral part of the development cycle Benefits users using the system Acts as resource for the helpdesk supporting.](https://reader035.fdocuments.net/reader035/viewer/2022062523/5a4d1b0d7f8b9ab05998c6f0/html5/thumbnails/18.jpg)
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
![Page 19: Why document? Documentation is an integral part of the development cycle Benefits users using the system Acts as resource for the helpdesk supporting.](https://reader035.fdocuments.net/reader035/viewer/2022062523/5a4d1b0d7f8b9ab05998c6f0/html5/thumbnails/19.jpg)
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/
![Page 20: Why document? Documentation is an integral part of the development cycle Benefits users using the system Acts as resource for the helpdesk supporting.](https://reader035.fdocuments.net/reader035/viewer/2022062523/5a4d1b0d7f8b9ab05998c6f0/html5/thumbnails/20.jpg)
Questions? Comments?Discussion!
![Page 21: Why document? Documentation is an integral part of the development cycle Benefits users using the system Acts as resource for the helpdesk supporting.](https://reader035.fdocuments.net/reader035/viewer/2022062523/5a4d1b0d7f8b9ab05998c6f0/html5/thumbnails/21.jpg)
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