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

Example - Thematic

Example - Reference

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

EBSP Tweet Poke

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 –“ ,” “ ,” “ ,” “ ” –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 – – Consider accessibility standards in the development process – – –

The good –“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.” –“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.”

Questions? Comments? Discussion!

References List

Contact Jessica Knott x101