Introduction to SD

What is Software Documentation?

Why we need Software Documentation? Who uses Software Documentation?

How we develop Software Documentation?

When we develop Software Documentation? Where we start?

This chapter helps documentation writers to achieve:

- Proficiency: encourage knowledge of the program. - Efficiency: encourage application of the program to the user’s job, proficiency helps achieving efficiency.

Always focus on one principle which it is: Make the software easy to use and usable.

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.

Scenarios, examples and a page layout can contribute to this explanation.

A manual that does this can be called “ task oriented”, because it helps the user to manage and communicate information related to his or her work

we will explore on this course 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.

What is task-oriented documentation

• 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 his or her work environment to discover the rich texture of activities within the software program and where the manual fits.

• This book has the technical communicators goal in mind--to be an advocate for our readers!

Quotes……

-Anger is never without a reason, but seldom with a good one. - Do good to your friends to keep them, to your enemies to win them.  - Eat to please thyself, but dress to please others.  - Half a truth is often a great lie. - He that is good for making excuses is seldom good for anything else.  - If a man could have half of his wishes, he would

double his troubles. - Keep your eyes wide open before marriage, half shut afterwards.

Guidelines for Successful Software Manual

1- Emphasize problem solving: The manual should have the goals and objectives of the procedures and steps to follow to solve problems in the workplace.

In “introductory overview” you can help the user not only in the steps to follow, but the goals and objectives of their software.

2-Provide Task Oriented Organization:

Task orientation should be spread all over the design of your manual. (from the table of contents and on),

So, organize your manual or online help in a way that matches the kind of tasks a user will perform, such as open a file, type in words, save the file, and exit the program.

3-Encourage User Control of Information: This means the feeling among users, that they decide what the program offers for them.

Show the user how to make key decisions, supply key information, determine key program output.

4-Orient Pages Semantically: Arrange the element of the page meaningfully according to the elements of the user need to perform.

Put important element first, larger fonts, and employ visuals and graphics to balance the text in your documents.

5-Facilitate Routine and Complex Tasks: Routine task include repeatable tasks that are easily represented by conventional procedure such as (save a file, delete a record..).

Complex tasks require the user to apply knowledge that is not easily codified in step by step procedure.

This knowledge consists of insider info that comes from years of experience.

6- Design for Users: User driven design means manual comes from the user needs rather than from models or templates of what a user guide should look like.

User driven design should allow user to: - find what they need. - understand what they found. - use what they understand appropriately. So user driven design, needs an extensive user analysis. (chapter 5)

7- Facilitate Communication Tasks: - Document designer should know what kind of information users communicate and to whom and help them achieving this.

- Document designer can help the user see the why behind the program features by analyzing what kind of info user needs and how they communicate.

(the user open a file so that he or she can communicate info to another person not for the sake of opening a file).

8-Encourage User Communities:

Task oriented manuals encourages users to identify and get helps from others. Some software has some features that encourage group or team work.

(Figure 1.4 page 7 shows an example of a user community web page for users of a media playing program.)

9-Support Cognitive(known) Processing:

- People always use mental model –cognitive schema-, that help them learn, process, and apply the information.

- Task oriented manuals uses principles of knowledge representation, parallelism and analogies to convey software features to workplace.

-These techniques (analogies and parallelism) allow user to absorb what manual has to say with as little effort as possible.

The more a manual can support productive work, the greater

the chance of acceptance and satisfaction by a user.

(Make users Proficient with software, and efficient in their jobs)

Goals of the User: 1- Learn how to use the program. 2- Apply the program to useful work.

Goals of Manuals or Help Screens: 1- Support the features of the program. 2- Tell how to apply the program to the user’s jobs

Quotes…. “Second Place is just the first place loser,”

"Coming together is a beginning. Keeping together is progress. Working together is success”

"Teamwork divides the task and multiplies the success"

Task Orientation: A design strategy for software documentation that attempts to increase user knowledge of applications of any program by: integrating the software with the user’s work environment.

The default (computer-Mediated) User: - A person who uses software for workplace ends, an operator instead of thinker.

- Computers not only do work for us, they record information about the work. (grocery store scanner, print receipt, update inventory, may be update some flags for statistics).

Characteristics & Difficulties (face default user)

1- Decreased importance of job skills, my experience isn’t good any more. 2- Increasingly abstract tasks, I just can’t understand how this thing works.

People have trouble seeing the link between doing by hand and doing with a computer lies to the abstract nature of computer work.(Violin & Piano- computer and pencil).

3- Increasingly Isolated from Other Employees, I’m stuck in front this computer.

4- Remotely Supervised, My boss has an electronic leash on me.

5- Overloaded with Information, why do I need to know that?, information anxiety.

The Task-Oriented User:

1- Challenged by Skill Demands:

- This program makes me a better user.

- The higher level skill require 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 concept, others learning with analogy.

- Difficulties when using 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)

3-Aware of User Communities: for those user using the same program.

User groups refers to groups that meet, electronically or in person, to discuss issues related to their job activities.

4- Self Managing:

- My software help 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, deadlines histories can use it to acquire important resources or plan effectively.

Three types of document can be created for each type of user: • Tutorial documentation: intends to teach the basic functions and

features of a program to 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 that 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, file formats.

Use Assistance- User assistance is a general term for guided assistance to a user of a software product. The phrase incorporates all forms of help available to a user.

- User Assistance can also automatically perform procedures or step users through the procedure, depending on the question that the user asked.

- User assistance provides information to help a person to interact with software.

- The term is broader than online help, and includes procedural and tutorial information.

-  User assistance employs a number of devices including help, wizards, tutorials, printed manuals, and user interface text

- User assistance bridge the gap between the users’ prior knowledge and the knowledge required to use the product.  - User assistance must not challenge the reader. Rather it should build up confidence, motivate the user to explore the product, and guide the user along the shortest way possible.

The processes of software documentation.  • It really begins by exploring what users are using the software for;

again, taking that human approach.

• This is a process of exploring user needs and then of constant involvement of the user in the process of writing and testing (this process is called usability process).

• Users and their needs drive the writing. Please see Figure 1.8 for the different stages of writing software documentation, which include the planning, development, and evaluation stages.

• Finally, “A manual that integrates a software program into the user’s environment has a better chance of getting used than a manual that only documents the features of the program.” Words of wisdom for all of us.

Automating: a process to convert a task from

one done by human to one done by a machine.

Cognitive schema: mental models of things,

organization that people form as away of interpreting their world. (kitchen is a room with stove, sink, refrigerator….)

Informating :term refer to the process of computer performing a task but also providing information about the nature of the task’s performance.

Information anxiety: experiencing an overloaded of data but not understanding how to use it. It is "produced by the ever-widening gap between what we understand and what we think we should understand. It is the black hole between data and knowledge, and what happens when information doesn't tell us what we want or need to know."

Construction of Task list for your system:

This section will help in analyzing the tasks (task list) a software program can perform and put these tasks in a form called task description, which create a descriptive model of the program features.

The task description may contain the task name and some descriptive detail, who erforms it, starting and goal state, steps, options, and screens.

Example of task list for Calendar maker program: 1. Installing the software onto the computer. 2. Creating a calendar. 3. Opening a pre-existing calendar. 4. Closing a calendar. 5. Saving an untitled calendar. 6. Saving a titled calendar under another name. 7. Printing a calendar. 8. Choosing the size of paper to print on.

Guidelines to construct your task list and task description: 1- Determine the right level of detail:

- Who will write the document, individuals or group (with group you may want to go into greater detail).

- What kind of interface do you have, the more complex the interface the more details you need.

- How much experience do the writers have (less details needed for expert because their knowledge on the system and standards, more details needed for new members on the documentation team)

-What is the stress level of your project, do you need to produce it quickly? You may have a time to perform a level one list, and then fill in the step later.

Major elements of task description are: a- Task Name, categorizing tasks, ex. transfer a file.

b- Steps, larger program, ex. select transfer from the file menu, select the desired file, click the transfer button.

c- Options, complex interfaces, ex. switch to another drive, cancel the transfer operation.

d- Screen, complex interface, ex. show screen.

Task Name: setting up a chart. User: end user. Starting state: MS chart is open, the user has created a spreadsheet document. Goals state: the parameters of the chart are set and it has plotted. Steps: 1. Choose the chart type.

Options:line chart icon: selects the line chartBar 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 first row2nd row: set value for second row.3rd row: set values for third row.

11. Click the plot button.

2-Categorize the program tasks:

- End use, tasks put the software to work, starting program, processing, sorting data, quitting, open a file, search for a record.

- Installation, tasks get the software onto the user’s system, copying program from distribution media, uncompress programs that have been compressed to fit on disks, running the installation program.

- Configuration, tasks get the software set up right, 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.

Characteristics of a task:

a- Independent. b- Short duration twelve steps or less. c- Goal oriented. d- Has starting and ending points. e- Made up of steps. f- Often relates to a menu function.

3- Link the task with menu feature:

- as a way of understanding tasks, consider that task refers to a well defined effort of short duration as hanging picture, starting the car, retrieving a record from a database.

- Because of the well-defined nature, tasks are independent of others, stand alone, have a starting and ending points, have steps 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, do not use the program oriented convention (the sort function) use instead sorting your data.

4- Write steps as actions: use the mouse to select OPEN from the FILE menu. Use appropriate details for each step. Consult the following guidelines when numbering and wording steps: - subdivide tasks if more than 12 steps - if the task requires tools say it “use the mouse to” - use numbers, bullets. - use the command verbs, click, press, type.

5- Don’t list options as steps, they should be part of the task description in order to show the users that they have many options of doing things.

You need to make sure that those options get stated clearly and accurately.

- Keyboard option, hot keys. - Menu options like cancel, return to menu options. - Mouse option, mouse, joystick.

6- Test your task list: the goal of task list is for accuracy, cmprehensiveness, and having the appropriate level of detail.

Why do we need a Task list? - A complete task list leads to complete manual or help system. How to get task information from programmers? Meetings, discussions, and interviews. Create a good relation with those partners.

Difficulties in communicating with programmers:

1- Their impression of what you doing is not important.

2- They moved to other project and they do not care about this one anymore.

Guidelines for interviewing programmers: - Emphasize the teamwork and team responsibilities.

- Ask the right questions.

- Prove you technical ability to understand their explanations.

- Use your interviewing skills: your job requires you to benefit from their expertise, show up on time, short interview one hour maximum, thanks them for their time.

Task description and Tutorials:

The next slide will show an example of a task

description from Microsoft Chart used for Tutorial

The slide after will show an example of a Tutorial lesson from a Microsoft Chart manual.

Task: setting up a chart. User: end user. Starting state: MS chart is open, the user has created a spreadsheet document. Goals state: the parameters of the chart are set and it has plotted. Steps: 1. Choose the chart type.

Options:line chart icon: selects the line chartBar 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 first row2nd row: set value for second row.3rd row: set values for third row.

11. Click the plot button.

A bar chart is making comparison easy. . To choose a bar chart: Click the icon for a bar chart ( a black dot appears in the circle next to 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 already selected everything you enter will replace the title… The next two boxes are for labeling the scales of the chart. To label the scales: 1- press the tab key t o 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 you 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….

Differences and Similarities: 1- Tutorial contains information not used in task description, in tutorial fields on the screens are filled out, task omits them, tutorial contains more explanations of what the options and task just list them.

2- Task description contains information not used in tutorial, some option listed in task description appears in tutorial, others do not.

- Tutorial contains different tone and language, because it speaks directly to the user. (Notice…. You…)

- Page layout and format is different, tutorials uses different indentations, styles to facilitate easy reading by the user. Task list uses a functional format for recording steps and options only.

Using task description to write Procedure :

A thorough task description includes all the elements needed to write a specialized procedure of a program such installation, and configuration tasks, but you need more explanation and elaboration on the following to help 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 environments. (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)

Use the task description for writing reference document: -Reference documentation relates to the task description as quick reference card.

-Reference documents are often list the name of task and give a brief steps.

-Most of the reference materials will consist of commands and short description, definition of key terms, table of keyboard shortcut, error numbers.

The purpose of reviewing task list and task description: - Communication function, help you communicate with people on project, provide 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. - Quality assurance function, help you maintain the quality of your product.

Do a user walkthrough: The technical reviews will focus on the accuracy and conformance with the company policies. The user review will contribute in helping you meet the task needs of employee, such questions will be answered in the reviews are:

- Does the document reflect the workplace task and goals? - Does the document support your info processing? - Does any task has been omitted? - Does the tone of the document suit your reading preference? - What order you think you will use the document?

How to set up a user Walkthroughs:

- Decide on the issue you want to examine. - Choose the attendees. - Make copies for all attendees. - Run the walkthrough. - Do a follow up review.