Installation and User Documentation ----------------------- slide number 1 Installation and User Documentation ______________________________ Outline Installation Training User Documentation - Specification User Documentation - Implementation Installation and User Documentation ----------------------- slide number 2 Aspects of System Installation Installation is much more than just moving a few files around. In general, installation includes: * Site and system preparation * Data conversion * Software installation & installation testing * Transitional operation * Training * Documentation * Acceptance testing * Tuning * Starting all over again Installation and User Documentation ----------------------- slide number 3 Software Installation Installation proper * "the obvious" might be overlooked under pressure hence planning and preparation typically not extensive note paths, parameters, etc. * script/procedure helps if available most PC software has an install procedure Installation testing * access each file * exercise each parameter * keep a log Installation and User Documentation ----------------------- slide number 4 How to Train Very often the user is asked to learn new ways of thinking in addition to new operations. User training should include * general concepts (mental road-map) * task-specific information * system navigation (how to follow the road map) * choice points * operations * exceptions too Installation and User Documentation ----------------------- slide number 5 Whom to Train Target separately: * Users * Clerical staff (possibly multiple targets) * Management * Systems administration * Systems maintenance Different jobs imply different modes of use: * rote versus mindful Hence different training tactics: * rote - task-oriented * like a recipe * recovery from exceptions * mindful - both general and task-specific cover both actions and consequences impact of choices on * task (navigation, changes in operations, ...) * system (updates, constraints, ...) Installation and User Documentation ----------------------- slide number 6 Design for Trainability Goal: enable the user to learn the system. * conceptual integrity Is there a simple mental model of the system? Are there effective metaphors? * consistency * reversibility * help for tasks and concepts * examples for tasks and concepts Installation and User Documentation ----------------------- slide number 7 Motivation Why write user documentation? * contractual obligations * commercial advantage * professional pride Installation and User Documentation ----------------------- slide number 8 Terminology Navigation: * through the system * through the documentation => keep both in mind Installation and User Documentation ----------------------- slide number 9 Documentation Process Documentation, like any other project activity, requires * thoughtful planning * systematic execution Specific requirements: * goals and objectives statement of thesis * specification and design outline * good presentation * evaluation Installation and User Documentation ---------------------- slide number 10 Targets of Documentation Identify Readers of Documentation: No one (well, almost no one) reads computer documentation for the fun of it. Hence, a reader of documentation has a particular purpose in mind. The identification of the end user(s) is by far the most critical factor for ensuring that your documentation will be useful to your client and profitable for you. - Hastings and King Once again the advice: ``Put yourself in the user's shoes.'' Installation and User Documentation ---------------------- slide number 11 Context for Documentation Knowledge Level of User: * software: * naive * computer literate * experienced with other software * experienced with this software * application domain: * novice * expert Sophistication of Software: * simple, complex, multi-system Frequency of Use: * daily, weekly, or occasional Variety of Use: * "canned" interaction, few or simple tasks, multiple interrelated tasks, operation * again, rote versus mindful Purpose of Documentation: * tutorial, general overview, or reference Installation and User Documentation ---------------------- slide number 12 Document Organization Analogy to Modularity: A single document should address a single user type and a single purpose. Most common ``modules'': * tutorial * general introduction * reference manual Analogy fails with respect to redundancy * modules limit redundancy to increase consistency * documents need redundancy and consistency hence documents must gain consistency other ways careful proofreading link, don't copy, if tools permit it Installation and User Documentation ---------------------- slide number 13 Document Organization Analogy to Design: Outline is like Preliminary Design (aside) We have now come full circle, since one of the first analogies for the design process was outlining a paper. Issue in Organization is Information Flow (order in which are concepts are introduced) * not relevant for reference manual Arises because * people are poor at forward-referencing => "spiral" organization Installation and User Documentation ---------------------- slide number 14 Reference Manual Goal: Fast Access to Information Navigation through the documents * table of contents access by general concepts * index access by details include all synonyms * cross references * tools provide consistency Installation and User Documentation ---------------------- slide number 15 Help Q: Is "Help" documentation? A: Yes, but there's more to documentation than just "Help". Once again, distinguish goals: * identification: what is _____? * navigation: where is _____? * operation: how do I _____? what does _____ do? * conceptualization: why does the system appear this way? Installation and User Documentation ---------------------- slide number 16 Writing Style "English is your most important professional tool. Use it with precision." Be consistent in form and terminology! Give directions: * using active voice * using second person * explaining consequences first - When the ENTER key is pressed, the system . . . -- Press the ENTER key in order to . . . + In order to . . ., [you should] press the ENTER key. Use outlines, lists, headers to * organize facts * distinguish facts * allow reader to digest facts separately Installation and User Documentation ---------------------- slide number 17 Presentation Suggestions * Use special fonts (or similar `marking') to indicate computer output, user input, etc. * Use positive voice, direct statements, simple syntax, ... * Use terms that indicate direct manipulation, for example say "press the ENTER key" rather than "select the ENTER key." * Don't confuse readers by digressing. * Don't use synonyms unless the equivalence is VERY clear. * Organize consistently and apparently apparently => user understands organization * by category * alphabetically Installation and User Documentation ---------------------- slide number 18 Content Suggestions Introduction purpose notation information content of system (possibly simplified data model) User Interface Operations cursor motion, selection, help, etc. less necessary as users gain experience Navigation Data Manipulation Operations entering master and detail records, etc. Installation and User Documentation ---------------------- slide number 19 Tools e.g. MS Help Compiler Help you: * organizing * indexing - another thing to learn Help user: * familiarity * context * indexing