Software Documentation

The following texts are the property of their respective authors and we thank them for giving us the opportunity to share for free to students, teachers and users of the Web their texts will used only for illustrative educational and scientific purposes only.

All the information in our site are given for nonprofit educational purposes

The information of medicine and health contained in the site are of a general nature and purpose which is purely informative and for this reason may not replace in any case, the council of a doctor or a qualified entity legally to the profession.

Software Documentation

Descriptive Answers ( in detail)

Explain the guidelines of Successful software Manual.
Emphasize problem-solving.
Provide task-oriented organization.
Support user control of information.
Orient pages semantically.
Facilitate information tasks.
Use multi-document support.
Design for users.
Facilitate communication tasks.
Encourage user communities.
Support cognitive processing

i) Emphasize problem-solving:
A manual or help system should help users solve problems in the workplace. Some problems might : "How can I organize this project?" "Where should our company invest development time?" etc..
ii) Provide task-oriented organization:

Organize a manual or help system in a way that matches the kinds of tasks a user will perform.
For example, a word processing manual that follows the "open a file, type in words, save the file, exit the program".
A task-oriented arrangement begins in the table of contents (of your manual) or the introductory screen (of your help system).

iii) Encourage User control of Information:

"User control of information" means the feeling, among software users, that they decide what the program does for them. To encourage this, the manual should show users how to make key decisions, supply key information, or determine key program outputs.
Examples include: specifying what a database program will search for and identifying which data the program will process.
Users need to feel in control of the program. Cross-references in manuals and hypertext links in online systems can help maintain the user's sense of control over the documentation because these document design elements allow users to choose where they go for additional information, or where to proceed after they have finished a section.

iv) Orient Pages Semantically :

Semantic orientationin page design means to arrange the elements of the page meaningfully, according to elements of the job the user needs to perform.
Examples of semantic organization include putting important elements first and making important elements larger to help users see the application of the program to their work.
One of the best way to orient pages semantically employs visuals and graphics to balance text in a complementary way.

v) Facilitate Information tasks:

All programs require information or help users create information they can use in their jobs.
For professionals, this information may include account data, analysis data from field studies,. or data collected from electronic measuring equipment.
Knowing how and where your user gets, stores, and shares information can help to find those functions of the program that support these tasks.

vi)Use multi-Document Support

Users like their manuals sectioned and divided according to tasks, such as the operator's manual, installer's manual, or executive's manual. Such sectioning can encourage the users' putting the software to work.
Users look for information online, in help screens, online references ,and online tutorials. Finding the right document types for users can facilitate their use of the software.

vii)Design for users.

The concept of user-driven design means that the organization of a manual comes from the user's needs rather than from models or templates of what a user's guide should look like or from schemes based on giving some users one kind of information and other users other information.
User-driven design requires the kind of extensive user analysis.
It means that each manual or help system presents you with new design challenges requiring to consider the user's job needs in regard to our program.

viii) Facilitate Communication tasks:

Users of software programs work in environments that require them-to communicate about their work.
Document designers can help them do this by analyzing what kinds of information they communicate and to whom, and then identifying those program functions.
For example, print functions, report functions, or disk output functions-that can help the users become effective communicators.

ix) Encourage User Communities:

Task-oriented manuals recognize that users often need encouragement to rely on other users of the program, their user community.
Task-oriented documentation encourages users to identify and get help from others.
Other users of the program, while not exactly experts in the software, can render valuable help because they understand the user's job demands.

x) Support Cognitive Processing:

People use mental models, called cognitive schema, that help them learn new information, process the information, and apply the information that comes at them at an alarmingly faster and faster rate.
The task-oriented manual uses principles of knowledge representation, parallelism, and analogy to convey software features and applications to workplace tasks.
Computers generate complex information, and computer software allows the user to store, transfer, and present it.
Our understanding of how computers affect work grows through research on the impact of computers on people's work and workplace roles.
What is task orientation? Explain the theory behind the Task Orientation.

Task Orientation :
It is an approach to Software Documentation that presents of information in chronological order based on the user’s workplace sequences.
(i) Computer mediated User
(ii) Task Oriented User

Computer Mediated User :

Recording of information about a task informating,which contrasts to simple automating.Persons who do informated work, work that involves computers and also involves keeping and managing information, face difficulties that other persons do not.
Consider the example, when the checker at the grocery store scans the purchases with a laser beam, more gets recorded than just the price and description of the item. The computer that reads the universal product code also records the frequency of sales and deducts the item from inventory stocks. It does the job and keeps track of the job at the same time.

Decreased importance of job skills
Increasingly abstract tasks
Increasingly isolated from other employees.
Remotely supervised.
Overloaded with information

Decreases Importance of job skills:

Job deskilling : A certain job is deskilled when the skills formerly needed to perform it are no longer needed and a person possessing lesser skills can be hired ,usually for less money , to perform the job.
Job deskilling which means that the computer program can perform many of the tasks a person used to perform so the job requires less skilled people.
In Inventory control system, parts are reordered automatically once the levels of inventory fall to predetermined levels, using computer.. The decision to order new parts, for example, has gone into the computer, so the company can now afford to hire persons with less job experience, with fewer special skills.
Job skills transfer into software skills, and Beginner skills transfer into advanced skills. The software manual should encourage advanced skills. The manual or online help writer must realize that many users have trouble seeing the connection between doing things by hand and doing things with a computer.
Increasingly Abstract Tasks:

“I Can’t understand how this thing works.
Anyone who has tried to learn a computer programming language has experienced the abstractness of the way computers do things.
Consider the example 1: Violin and piano
Compare by-hand work and computer work to playing the violin and playing the piano. Both instruments make music, but in very different ways. The violin creates sound directly when the bow causes the string to vibrate. We can not see the sound being produced. But piano keys activate a complex system of levers, rockers, and hammers that finally produce the sound.
Example 2 : Computer
The computer uses a highly complex, electronic system of buffers, wires, computer chips, and circuits to leave its visible phosphorescent trail on the screen. The computer does things in a very abstract way.
Increased abstraction relates to how people see their jobs through their tools-computerized or not-work also takes place in a social domain. And that, too, appears threatened by computer-mediated work.

Increasingly Isolated from other employees:

"I'm Stuck in front of this computer".

Social structures-the people we relate to at work, the work communities we inhabit, the coalitions we form-play a major role in our job satisfaction.
In some companies, social groups take on names: the front office, the back office, the first floor, and so on. "No talking, no looking, no walking.”
People need others to communicate with, to get feedback from, and to get rewards and other incentives that make work enjoyable. They create useful dialogs with others to help share and solve problems.
But people using computers risk a diminished importance of their co-workers in their job. They lose their social contact, even if, before, they may not have realized the social aspect of their work.

Remotely Supervised:

“My Boss has electronic leash (band) on me”
The supervisor can check on the secretary by looking up the file on the network. The manager can access your files electronically, check on your productivity, even organize your work day for you without ever showing up physically.

Overloaded with information :

“Why do I need to know that?”

Computers produce lots of information very quickly. Anyone who has used a word processing program knows that it can count words in a document more quickly than a person can.
Some users resist computer use because they feel overloaded by information.
Computer users face many problems with information overload. On the one hand , they need ways to filter, to sift through and make sense of the information that floods them.

(ii)Task Oriented User
Task Oriented:
A method of organizing online and hard-copy documentation that follows the typical tasks and task sequences of the software user.
Characteristics:

Challenged by skill demands
Conceptually oriented
Aware of User communities
Self managing
Information Rich
Challenged by Skill demands:

“This program makes me a better manager”

While software can perform some of the skills of trained employees, most of the time the higher-level skills require the human mind. A computer can sort and categorize but it cannot handle ideas.
The software documenter needs to find ways to reinforce the skill challenges inherent in efficient computer work.
Training materials should consider the need for skill transfer from a person's non-automated job to his or her computer-mediated job. Additionally, software support should reinforce decision making and problem solving as important computer skills.

Conceptually Oriented:

“This give me something new to think about”

Technical writers have always faced the challenge of explaining abstract and highly technical information to novice readers.

Documentation that uses the appropriate training method is conceptually oriented.
Conceptually oriented documentation concentrates on the ideas the user needs to operate and handle the information generated by a software program. Advance organizers help users understand instructions by providing a context for each step.
When users perform the step, they have a clearer idea of the outcome and relevance of their actions.
Computer technology allows graphics to be used much more freely and with greater effectiveness than before, both in manuals and online help.

Aware of User Communities:

User Community : A group of users who use the same program. They may exist within the user’s organization or within the larger community, and may be organized according to various degrees of formality
User Groups:
The term user groups refers to groups that meet to discuss issues with their computing and exchange ideas to increase efficiency and productivity.

Meeting with these groups allows users to increase their social contacts within an organization and overcome any sense of isolation they may feel..
Most employees work in groups and as a result have to coordinate their activities, share work in progress, and store the results.
This collaboration often creates situations in which managers must produce group reports or engineers must contribute designs of parts to an overall project.

Self Managing:

“My Software Helps me sort out my Work”.

Software opens up many opportunities for self-management.
To emphasize self-management the documenter should clarify the position of authority that the user has over the program.

Statements like "You can do this with the program. “ help the user maintain an appropriate attitude of instrumentality and self-management with regard to the program.
Information Rich:

My Software Gives me a better view of my tasks:
Software gives users new opportunities to manage information.
In organizations today, information has become thecurrency. Those who control information-about production statistics, about deadline histories, about efficiency ratings-can use it to acquire important resources or plan effectively.
Consider the manager who keeps track of production times through automated tracking of past projects. Such a person can plan future projects much more accurately than before, saving time and money for the organization. Such a person gains the power to speak with authority at meetings because of the soundness of the support for projected dates of completion and resource needs.
In modern corporations, information represents the source of power and authority.

Explain the Guidelines of conducting User Analysis

i) Choose Users Carefully

During the first part of the research process, identify users according to the types of task they perform: installation, configuration,and end use.
To build the list of job tasks, pay particular attention to information-related tasks: communicating, storing, sharing. Identify users with these concerns.
In large organizations, they have large number of users that just install and configure software, but most of the users will need to perform end-use tasks.
In smaller organizations they may have one user, or the owner of the program, performing all tasks.

Program	User Group	Tasks
Network	System Administrator	Set up User Accounts and passwords
	User	Log in, run progress, store files
Jogging Log	Coach	Enter data about athletes , create reports, track progress.
	Athlete	Enter data about workouts, Create reports, track progress.
Math Tutor	Teacher	Set up tutorials, track progress
	Student	Run tutorials, score tests, record progress
Family	Financial Consultant	Create customer profiles, reports for customers
Financial planner	Head of household	Enter data about assets, income, investment, create tax reports.

Anticipate Transfer of Learning by studying Non Computer-Mediated tasks:

(Expect in Advance)

In User interview , collect the wealth of information about a particular user.
For example in word processor, Know about how the (user) he or she writes, as well as about how he or she would use the word processor.
On the other hand, if the user conducts mathematical research, find out what computational tasks he or she performs, as well as more hypothetical information about what he or she might do with the graphing software.
Research shows that skills learned in the workplace can transfer to skills using software.
Learn what other types of employees the user interacts with. Find out what values- efficiency, team orientation, environmental concerns, ethical issues-confront your user, and how he or she responds to them. Such information can help to understand the motivation of users .

Mock up hard to contact users:

In some instances we do not have actual users at the disposal. We may find ourselves without actual users to interview and only limited information about the tasks the software supports.
In the absence of the users, we can construct a mock-up of the user, a kind of model to use as a resource in making design decisions. Do this by focusing on the user's occupation as described in easy-to-find library materials.

Write User Scenarios:

User scenarios depict the tasks that users of the software would perform, based on your interview notes.
It helps you visualize users and creates a useful document that you can share with clients, potential users, or other members of the writing team.

Scenarios :

Scenarios should describe how the program gets used.
They identify what tasks the user will need information about, and what manuals that need to write.
The documentation has special sections for each type of user
In user scenarios, some of the elements will overlap with documentation needed for other users or will be used by other users.
Review your user scenarios carefully.

Elements of User Scenario: Professional Role, Profile, Overall Use of the Program, Typical use of the program.

Plan Interviews Carefully:

Known as research or background research.
Interviews with users provide the most important source of information for planning your documentation project.
In an interview, encounter potential users of the program and, often in one or two settings, learn enough to design a documentation system that will satisfy the goals as a writer: to encourage them to learn the features of the program and put the program to useful work.

Process of interviewing users:

Making site visits, spending an hour or two with a potential user, and getting potential users to fill out questionnaires.
A full user analysis should not only study users in one or two episodes, but should involve users in the whole documentation cycle.

In conducting Interviews concentrate the following steps :
Know Users , Know the programs, Prepare list of questions, collect samples, Observe well, prepare Questionnaires.

Involve Users in all phases of the project:

A full user analysis should not only study users in one or two episodes, but should involve users in the entire documentation cycle. Usually, involving the users in the process can have the following benefits:
Increased accuracy :Users can indicate mistakes or lack of clarity in manuals.
More appropriate information. Users can identify information that is not useful to workplace tasks.
Increased usability. Users can advise on the most useful design techniques for information.
Empowered readers. Users can help plan the documents they need most.
Improved politics. Users are flattered to be consulted.

The idea of involving users in the documentation process relates to two other key ideas:

Usability: Making sure of the readability of the documentation and its suitability to the task.
Collaborative writing: Users and documentation specialists collaborating to produce the documentation product.

Involve users in the following production phases :

Performing the User Analysis.
Creating the program task list.
Designing the documents
Writing the project plan
Writing the Alpha Draft
Conducting Reviews and tests
Revising and Editing
Writing a Final Draft
Conducting a field Evaluation

Cultivate relationships with others:
When we make initial contact with users ,plan to include them in as much of the documentation work.
Learning about the users on one project will be useful on subsequent projects
Make the relationship with with programmers, managers , testing specialists etc.
Focus Group:

Identify Document Goals :

For a documentation project ,we can communicate the goals to other writers, managers, and clients.
Goals can come in very handy.
To encourage the users to learn features of the program and to put those features to work.
In a document design , a way to guide decisions about page layout and text design.

Typical Goal Statements:
(a) Section of a document : Different sections are available for different types of users (Novice users, experienced users, and expert users)
(b)Booklet: ‘Getting Started’ Booklet will provide tutorial support fro novice users in education and business.
(c) Chapter : Provides reference support.
viii) Tie the user Analysis to Documentation Features:

while conducting user analysis, state the details of your document design: the page layout, choice of type size, style, fonts, or stylistic choices.
The level of design results from considering the many design tools available to the writer.

Descriptive Answers ( in Short)

. (i) Explain the guidelines of Planning Documentation Project?

                (ii) Define Review Schedule. Explain any one of Circulation
strategy in Scheduling a review.
Ans :
(i) Guidelines for planning Documentation Project

Create a Task sheet
Work backwards from Delivery date
Assign people to tasks
Work in the Drop –Dead mode
Make the Documentation plan persuasive

Definition of Review scheduling :

It means that to give the reviewers enough time to prepare their response and to decide on the right circulation strategy.
Two methods: Any one
(i) Sequential Circulation
(ii)Simultaneous circulation

Explain about ‘Ten Step Test Plan’ in detail?

Decide when to test
Select the test points
Choose the type of test
Set performance objectives
Select testers and evaluators
Prepare test materials
Set up the test environment
Record information accurately
Interpret the data
Incorporate the feedback

(i) Briefly explain the Advantages of Field Testing. ?

(ii) Explain any four guidelines of Designing Documents ?
Ans :
(i) Advantages of field testing.

Do preliminary research into the company and the users we want to test
Construct a sensible field testing plan
Prepare to compromise

(ii) Any four guidelines of designing documents :

Follow a problem solving process
Meet task needs
Try out ideas on users
Examine existing documentation
Review User analysis
Acknowledge production constraints
Design the documentation as a system

Explain the stages of Documentation process
Perform the User Analysis
Develop the program schedule
Design the documents
Write the project plan
Write the Alpha Draft
Conducts Reviews and Tests
Revise and Edit
Write a Final Draft
Conduct a Field Evaluation

Explain the steps involved in Editing the Documentation.

Guidelines of Editing Software Documentation

Know your users
Take a Constructive attitude
Don’t edit your own on your own
Use Editing forms
Edit Strategically
Develop an editor’s reading skills
Consult Standard Style guides
Don’t confuse editing tasks with other tasks.

(i) Explain all the elements of page Design

(ii) Explain all the elements of screen design
Ans :
(i) Elements of page design :

The left margin
Columns
Headers and footers
Icons and diagrams
Screens
Rules
Pagination

(ii) Elements of screen design:

A changeable space
Multiple Window management
Color
Graphics
Screen grids
Line spacing

Explain the guidelines for using graphics effectively

Answer Users’ Questions
Make it Visible
Keep Graphic styles consistent
Don’t over-do graphics
Label consistently
Use Typographic Technique
Size the image correctly

Explain all the solutions to the design problem of printed Documentation.

Navigation
Cross Reference
Headers and footers
Color to indicate sections
Layering
Advance organizers
Document overview
Parallel structures
Patterns of redundancy
Cuing
Indexes and tables of contents
Lists of figures and tables
Lists of screens

(i) Explain the Guidelines for designing pages and screens

(ii) What are the common page designs ? Briefly explain about all.

Ans :
(i) Guidelines of designing pages and screens :

Create Page grids
Draw Thumbnail sketches
Define styles for pages and screens
Set up pages and styles in your word processor
Online Help can repeat printed information.

(ii) Common page Designs :

Two Column format
One Column format

Source : http://www.niceindia.com/qbank/software_documentation_essay_.doc

Web site link to visit: http://www.niceindia.com

Google key word : Software Documentation file type : doc

Author : not indicated on the source document of the above text

If you are the author of the text above and you not agree to share your knowledge for teaching, research, scholarship (for fair use as indicated in the United States copyrigh low) please send us an e-mail and we will remove your text quickly.