Chapter3- Understanding task oriented .pdf

SOFTWARE DOCUMENTATION AND TECHNICAL WRITING Dr. Hanadi Mardah [email protected] Computer Science Department Umm Al-Qura University First Semester 2024/1446 Chapter 3: Understanding Task Orientation AND Constructing Task List 2  Understanding Task Orientation and Constructing Task List T...

SOFTWARE DOCUMENTATION AND TECHNICAL WRITING Dr. Hanadi Mardah [email protected] Computer Science Department Umm Al-Qura University First Semester 2024/1446 Chapter 3: Understanding Task Orientation AND Constructing Task List 2  Understanding Task Orientation and Constructing Task List This chapter helps documentation writers to achieve: Proficiency: encourage knowledge of the program. It means having deep understanding and high level of skill in a task. Efficiency: encourage application of the program to the user’s job. It means completing tasks quickly with minimum wasted effort. Proficiency helps achieving efficiency. It makes the software easy to use. A manual that does the above, adapts the software to the user’s job, rather than making the user adapt to the software. All software documentation should explain and show the connections between the user’s professional work and the computer program. A manual that does this can be called “ task oriented”, because it helps the user to manage and communicate information related to the work. 3 3 Software Documentation and Technical Writing  Understanding Task Orientation and Constructing Task List We will explore the techniques that can help you create a manual or help system that focus on helping the user clearly see the relation between the program and their workplace. Task-orientated documentation is really the challenge of creating documentation that looks at the process of writing and finds ways to learn about users. Task-orientated documentation consists of manuals and help that reflect real users and human forms. The process of task-orientated documentation requires that you analyze the user in work environment to discover the rich texture of activities within the software program and where the manual fits. 4 4 Software Documentation and Technical Writing  Guidelines for Successful Software Manual Task Orientation: A design strategy for software documentation that increases user knowledge of program applications by integrating the software with the user’s work environment. 1- Emphasize problem solving: 2- Provide task-oriented organization: The manual should have the goals and Task orientation should be spread all over the objectives of the procedures and steps to design of your manual. (from the table of follow to solve problems in the workplace. In contents and on), so organize your manual or “introductory overview” you can help the user the online help in a way that matches the kind of with the steps to follow and the goals and tasks a user will perform, such as opening a file, objectives of their software. typing in words, saving the file, and exiting the program. 5 5 Software Documentation and Technical Writing  Guidelines for Successful Software Manual 3- Encourage user control of Information: 5- Facilitate Routine and Complex This means the feeling among users, that they tasks: decide what the program does for them, show Routine tasks include repeatable tasks the user how to make key decisions, supply key that are easily represented by a information, and determine key program output. conventional procedure such as (saving a file or deleting a record..). Complex 4- Orient pages semantically: tasks require the user to apply Arrange the elements of the page meaningfully knowledge that is not easily codified in according to the elements of the user need to step by step procedure. This knowledge perform, put important elements first, and larger consists of insider info that comes from fonts, and employ visuals and graphics to years of experience. balance the text in your documents. 6 6 Software Documentation and Technical Writing  Guidelines for Successful Software Manual 6- Design for users: 7- Facilitate communication tasks: Document designers should know what User-driven design means manual comes from kind of information users communicate and the user needs rather than from models or to whom and help them achieve this. templates of what a user guide should look Document designers can help the user like. User-driven design should allow users to: see the why behind the program features Find what they need. by analyzing what kind of info users need Understand what they found. and how they communicate. (the user Use what they understand appropriately. opens a file so that he or she can So user-driven design needs extensive user communicate info to another person, not analysis. for the sake of opening a file). 7 7 Software Documentation and Technical Writing  Guidelines for Successful Software Manual 8- Encourage user 9- Support cognitive(known) processing: communities: People always use a mental model -cognitive schema-, Task-oriented manuals that helps them learn, process, and apply the encourage users to identify information. and get help from others. Task-oriented manuals use principles of knowledge Some of the software has representation, parallelism and analogies to convey features that encourage software features to the workplace. group or teamwork. These techniques (analogies and parallelism) allow users to absorb what the manual has to say with as little effort as possible. 8 8 Software Documentation and Technical Writing  User and Manual Goals The more a manual can support productive work, the greater the chance of acceptance and satisfaction by a user. Goals of the user: Learn how to use the program. Apply the program to useful work. Goals of Manuals or Help screens: Support the features of the program. Tell how to apply the program to the user’s job. 9 9 Software Documentation and Technical Writing  The Task - Oriented Users The Task-Oriented User: 1. Challenged by Skill Demands: This program makes me a better user. The higher-level skill requires the human mind. Computer activities require actions (writing a letter) and operations (opening a file, setting a margin, checking spelling, selecting a font..) 2. Conceptually Oriented: This gives me something new to think about. Preference learning, some people have an easier time learning abstract concepts, while others learn with an analogy. Difficulties when using a computer that you have to learn more than your actual work. (For example, you have to learn internet security, encryptions… etc when you use a billing application program) 10 10 Software Documentation and Technical Writing  The Task - Oriented Users The Task-Oriented User: 3- Aware of User Communities: for those users using the same program. User groups refer to groups that meet, electronically or in person, to discuss issues related to their job activities. 4- Self-managing: My software helps me sort out my work. The program will do this and you can do this with the program. 5- Information Rich: My software gives me a better view of my tasks. Information has become the currency. Those who control information about production statistics, and deadlines histories can use it to acquire important resources or plan effectively. 11 11 Software Documentation and Technical Writing  Construction of Task list for your system Analyzing the tasks (task list) a software Example of the task list for the Calendar Maker program can perform and put these program: 1. Installing the software onto the computer. tasks in a form called task description, 2. Creating a calendar. which creates a descriptive model of the 3. Opening a pre-existing calendar. program features. 4. Closing a calendar. The task description may contain the 5. Saving an untitled calendar. task name and some descriptive detail, 6. Saving a titled calendar under another name. who performs it, the starting and goal 7. Printing a calendar. state, steps, options, and screens. 8. Choosing the size of paper to print on. 12 12 Software Documentation and Technical Writing  Guidelines to Construct a Task List and A Task Description 1. Determine the right level of detail: o Who will write the document, individuals or groups (with a group you may want to go into greater detail). o What kind of interface do you have, the more complex the interface the more details you need. o How much experience do the writers have (fewer details are needed for experts because of their knowledge of the system and standards, but more details are needed for new members of the documentation team) o What is the stress level of your project, do you need to produce it quickly? You may have time to perform a level one list, and then fill in the step later. 13 13 Software Documentation and Technical Writing  Participation in the Class To Do: How to improve the task list? 14 14 Software Documentation and Technical Writing  Guidelines to Construct a Task List and A Task Description 1. Determine the right level of detail: Task Name: setting up a chart. User: end user. o Major elements of task description are: Starting state: MS chart is open, and the user has created a spreadsheet document. o Task Name, categorizing tasks, ex. transfer Goals state: the parameters of the chart are set and it has been plotted. Steps: a file 1. Choose the chart type. Options: o Steps, larger program, ex. select transfer line chart icon: selects the line chart Bar chart icon: select the bar chart 2. Type the chart title. from the file menu, select the desired file, 3. Type the vertical scale title. 4. Type the horizontal scale title. and click the transfer button. 5. Choose the values to be Plotted. Options: o Options, complex interfaces, ex. switch to 1st row: set value for the first row 2nd row: set value for the second row. another drive, cancel the transfer operation. 3rd row: set values for the third row. 6. Click the plot button. o Screen, complex interface, ex. show screen. 15 15 Software Documentation and Technical Writing  Guidelines to Construct a Task List and A Task Description 2. Categorize the program tasks: End use, tasks put the software to work, starting the program, processing, sorting data, quitting, opening a file, and searching for a record. Installation, tasks get the software onto the user’s system, copying the program from distribution media, uncompress programs that have been compressed to fit on disks, and running the installation program. Configuration, tasks get the software set up right and set up the software so it will work in the user’s hardware environment. Customizing, setting options, setting preference. Some programs may combine installation and configuration in one task. 16 16 Software Documentation and Technical Writing  Guidelines to Construct a Task List and A Task Description Characteristics of a task: Independent. Short duration twelve steps or less. Goal oriented. Has starting and ending points. Made up of steps. Often relates to a menu function. 17 17 Software Documentation and Technical Writing  Participation in the Class To Do: How to improve it using characteristics of the tasks? 18 18 Software Documentation and Technical Writing  Guidelines to Construct a Task List and A Task Description 3. Link the task with the menu feature: As a way of understanding tasks, consider that a task refers to a well-defined effort of short duration as hanging a picture, starting the car, or retrieving a record from a database. Because of the well-defined nature, tasks are independent of others, stand-alone, have start and end points, and have stepped in between the starting and ending points. Seldom rely on a task list from the project manager’s desk. (use the project specs to identify tasks but do not depend on them) Identify all tasks your program can perform. Use certain conventions in naming tasks, use the ‘ing’ term, and do not use the program- oriented convention (the sort function) use instead of sorting your data. 19 19 Software Documentation and Technical Writing  Guidelines to Construct a Task List and A Task Description 4. Write steps as actions: 5. Don’t list options as steps use the mouse to select OPEN from the FILE They should be part of the task description to menu. Use appropriate details for each step. show the users that they have many options for Consult the following guidelines when numbering doing things. and wording steps: You need to make sure that those options are Subdivide tasks if more than 12 steps stated clearly and accurately. if the task requires tools say “use the mouse to” Keyboard option, hotkeys. use numbers and bullets. Menu options like cancel, and return to use the command verbs, click, press, and type. menu options. Mouse option, mouse, joystick. 20 20 Software Documentation and Technical Writing  Guidelines to Construct a Task List and A Task Description 6. Test your task list: The goal of the task list is for accuracy, comprehensiveness, and having the appropriate level of detail. Why do we need a Task list? - A complete task list leads to a complete manual or help system. How to get task information from programmers? Meetings, discussions, and interviews. Create a good relationship with those partners. 21 21 Software Documentation and Technical Writing  A Task List and A Task Description The purpose of reviewing task list and task description: Communication function helps you communicate with people on a project, provides you with a way to share your work with others, to let them know what you are doing and get their contribution. Management function helps you manage your project and allows you to touch base with everyone’s schedule. The quality assurance function helps you maintain the quality of your product. 22 22 Software Documentation and Technical Writing  Task description and Tutorials Example of a task description from Microsoft Charts used for the Tutorial Task: setting up a chart. User: end user. Starting state: MS chart is open, and the user has created a spreadsheet document. Goals state: the parameters of the chart are set and it has been plotted. Steps: 1. Choose the chart type. Options: line chart icon: selects the line chart Bar chart icon: select the bar chart 2. Type the chart title. 3. Type the vertical scale title. 4. Type the horizontal scale title. 5. Choose the values to be Plotted. Options: 1st row: set value for the first row 2nd row: set value for the second row. 3rd row: set values for the third row. 11. Click the plot button. 23 23 Software Documentation and Technical Writing  Task description and Tutorials Example of a Tutorial lesson from a Microsoft Chart manual. A bar chart makes comparison easy.. To choose a bar chart: Click the icon for a bar chart ( a black dot appears in the circle next to the icon, indicating what chart type is chosen). Notice that the work has proposed a name for the chart definition…..based on the name of the spreadsheet document. You can give any chart title.. The chart title is already selected everything you enter will replace the title… The next two boxes are for labelling the scales of the chart. To label the scales: 1- press the tab key to select the vertical scale title. 2. Type thousands 3. Press the tab key to select the horizontal scale title text box. 4 Type months.. Choose the values to plot To enter spreadsheet information for your chart, use the Tab key to select each text box, then type the appropriate information. - For the first row, type 6 - For the second row, type 7 - For the ending column, type D.. PLOT the chart … with the dialog box filled in you are ready to see some pictures…. 24 24 Software Documentation and Technical Writing  Task description and Tutorials Differences and Similarities: The tutorial contains information not used in the task description, tutorial fields filled out, the task omits them, and the tutorial contains more explanations of what the options and the task just lists them. The task description contains information not used in the tutorial, some options listed in the task description appear in the tutorial, while others do not. The tutorial contains different tones and language because it speaks directly to the user. (Notice….You…). Page layout and format are different, tutorials use different indentations, and styles to facilitate easy reading by the user. The task list uses a functional format for recording steps and options only. 25 25 Software Documentation and Technical Writing  Three Types of Documents for Each Type of User Tutorial documentation: intends to teach the basic functions and features of a program so a person can begin applying the program to workplace tasks. Examples: getting started guides and online tutorials. Procedural documentation: intends to guide the user in everyday use of the program, often when the users need information at the time of user. Example: step-by-step procedures. Reference documentation: intends to supply information "about" the program to advanced users who rarely consult the user's guide or tutorial but occasionally need to look up information about the program. Example: alphabetical listings of program features, lists of examples, and file formats. 26 26 Software Documentation and Technical Writing  Using Task Description to Write Procedure A thorough task description includes all the elements needed to write a specialized procedure of a program such as installation, and configuration tasks, but you need more explanation and elaboration on the following to help the user apply the feature to specific tasks: Emphasize user choice, you can choose if you use the mouse. Give reasons for choices, “ this is because” tells the user why something operates the way it does. Apply features to a specific environment. (it is best to use this option when…) Give useful advice, “You should use this option often”. Give illustrative examples. Give the result of the screen.(The Record Macro dialog box appears) 27 27 Software Documentation and Technical Writing  Using Task Description for Writing Reference Document Reference documentation relates to the task description as a quick reference card. Reference documents often list the name of the task and give a brief step. Most of the reference materials will consist of commands and short descriptions, definitions of key terms, a table of keyboard shortcuts, and error numbers. 28 28 Software Documentation and Technical Writing  References Writing Software Documentation, 2nd edition, Thomas T. Barker, Longman Publishers, 2004 https://www.slideshare.net/slideshow/software-documentation-ch-5-writing-to-support- references/229482546 https://www.cs.kent.edu/~nalhinda/SD/SD-CH-1.ppt 29 29 Software Documentation and Technical Writing