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

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

4. Example - Tutorial http://help.breeze.msu.edu

5. Example - Thematic http://www.nps.gov/nr/publications/bulletins/nrb16b/INDEX.htm

6. Example - Reference http://www.wikipedia.org

7. Starting the process…

8. Identify your audience For whom are you documenting? End users? System administrators? Non-technical people? Technical people? Training manuals? All of the above?

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

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

11. Five tips: making it easy

12. 1 - Keep it Concise Short sentences –Limit segments of narrative text

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

14. EBSP Tweet Poke

15. 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 ?

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

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

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

19. 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/

20. Questions? Comments? Discussion!

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

22. Contact Jessica Knott jlknott@msu.edu 517.432.0711 x101