Engl476576

Barker Chapter 12

2007-05-04T07:37:00.000-07:00

Barker – Chapter 1; Getting the language right.
This chapter is mostly a series of tidbits advising you how to write certain topics.

1) Write about Actions rather than Functions.
Tell the reader what they can do with a tool, rather than describe the tool itself.
Bad:
Hyperlink: Inserts a hyperlink or edits the selected hyperlink.
Good:
Hyperlink: This button allows you to link selected text to other text or documents or edit the properties of selected hyperlinks.

2) Revise for the Active Voice
The active voice puts a subject at the beginning of each sentence, a verb in the middle, and a receiver of the action at the end.
Bad:
The file menu is used to…
Good:
You can use the file menu to…

3) Revise to keep Writing Simple
Break down complex sentences in order to enhance the reader’s ability to understand your meaning the first time they read it.

4) Revise to Build Parallel Structures
Try to be a little repetitive in your writing; it helps the readers mind organize steps, for instance, when they all begin with an action verb.

5) Add Operational Overviews
Use a paragraph to give a conceptual overview of the steps before listing the steps.

6) Make sure topic matches Heading
If your heading states something general, don’t get overly specific.

7) Don’t use too formal a tone
Often when writing, the writers tone takes on the feeling or a robot or telegraph. Try to sound slightly conversational, even in a business setting, to keep the user engaged.

8) Use Humor with Caution
There’s a lot of opportunity for humor to fall flat. Never use it in reference sections, seldom use it in procedures, occasionally in tutorials or background information.

Rockley Chapter 8 - Delinquent

2007-05-02T17:49:00.000-07:00

I apologize for the late posting! Hope it hasn't caused too much inconvenience.

Chapter 8 - Information Modeling - Anne Peterson

In this chapter, modeling refers to formalizing a structure with writing and style guidelines, templates, and structured frameworks. Rockley says that it's critical to do a thorough analysis of information and its audience(s) when creating the model.

Rockley likens information architecture to the blueprints needed to build a house. It defines how content will be organized and structured for "information products" such as user guides, catalogs, documents, brochures, press releases, annual reports, intranets, Web sites, or technical specifications. Information architecture, done properly, requires a company to thoroughly examine all their content and catalog it.

Each of the information products listed above adheres to unique structural elements that identify them. It is important to understand the different types of structures. As content writing advances to Document Type Definition (DTD) it is even more important to understand structure and how it works.

The level of detail in a model depends on granularity, which determines the smallest possible piece of content that will be reused. There are different levels of granularity for authoring, resue, and delivery. Rockley says the greater the granual level, the greater the complexity of modeling, authoring, and managing the content.

After determining granularity, the model can start to be built. Some elements are mandatory and some are optional. There are information product models and individual element models.

Models can be made up of the following components:

Semantic information - uses semantic tags to describe what goes into each element
Base information - describes the common naming of each element using generic tags
Metadata - provides data about data
Architectural information - provides details on type of reuse

Rockley says that once the models are developed, they must be implemented throughout the organization so all authors and reviewers can use them as they create, edit, and review content.

Barker chapter 14: Designing Indexes

2007-04-29T22:49:00.000-07:00

With in this chapter Barker explain the importance of the index and the reason for indexing.
The importance of the index lies with in whom the potential users of the index maybe. Figuring out what the user of the material in which the index is for is how the index will mainly be designed.
Barker has five guidelines for designing an index

Plan your indexing strategy
Decide what to index
Identify the level of detail
Decide on phrasing and formatting
Edit and proofread

Planning your index strategy involves which method of indexing you will be doing, either manual or electronic. The first step in designing and building an index which Barker mentions is to review the user analysis by refreshing your memory about what the user’s main activities and actions are with the software or manual. The next steps are different depending whether you are designing an electronic index or manual one. With indexing a manual you need to read or scan for terms or phrases of importance, record the locations of the terms or phrases, and alphabetize and edit the index. For electronic indexes the second step is to mark the index entries, building the index and editing the index. As you maybe able to tell indexing electronically is much fast. You can use electronic marking software to help in marking and building the index. The second step in designing is deciding what to index. Some of the elements Barker mentions for indexing are commands and functions, concepts, user terms and questions, glossary terms, proper names of products and companies, and tasks and procedures. The third guideline is identifying the level of detail. The levels of detail can be determined by the number of levels in the index or by the number of items that you index. The forth guideline is deciding on phrasing and formatting. Barker reminds us that deciding on phrasing and formatting does take some time so be prepared. Phrasing and formatting focuses on cuing of primary locator numbers, capitalizing terms consistently, making the entries sound like sentences, which will help in being more detailed of what the user maybe looking to do, and cuing special terms. The fifth guideline, editing and proofreading Barker again reminds us that this step will take up about 1/3 of the indexing project. Index editing includes checking the page references, and inconsistencies of referenced items.

Rockley ch 11

2007-04-27T08:52:00.000-07:00

Disclaimer: Please do not take away from students who do not comment on this blog because it was supposed to be posted in early April.

Rockley Chapter 11: Designing Workflow.

Rockley describes what workflow charts are, what content they hold, and the pros for utilizing them in tandem with the unified content strategy.

A workflow chart is basically a flowchart with the various aspects (role, responsibility, and process) of a project planned out. Workflow charts can be flowcharts or swimlane charts. I find the swimlane chart the easiest to follow because it is like looking at a table, find your lane and follow it along to see what tasks are yours to complete.

Workflow charts work well into the unified content strategy because it is an easy way for every player to get on the same page with what tasks need to be done and in what order.

2007-04-26T18:15:00.000-07:00

Chapter 21—Managing Change

Rockley discusses change in organizations in this chapter. In all organizations people resist change unless they believe there is a reason for the change.
Promoting Change
One key to making change happen is to listen to comments about the change from the people who the change will affect. Rockley lists some things she considers essential to change management including:
§ Communication—communicate the reasons for change.
o Explain why change needs to occur
o Explain your plan for the change
o Keep people informed as change occurs
o Communicate achieved successes
o Inform people of problems that may occur
§ Use “change agents” to help assimilate the change. Change agents should be people who will be a user of the new technology and who embraces the change that will occur.
§ Have a champion who is high enough in the organization to make the change happen regardless of the endorsement or opposition of company personnel.
Challenges
Challenges to the changes will occur regardless of where the changes originate. Some of the common challenges include:
§ These ideas are from a different company. Content can sometimes be reused if writers use care to format it correctly.
§ We don’t do it that way here. Find the commonalities between all segments of the company and implement them.
§ Creativity issues. With unified content, content must use formatted and structured templates. Creativity might be the domain of the authors of the templates, with some creativity reserved for departments who need to modify templates (such as marketing).
§ Workload issues. While there will be more work at the beginning of the cycle, workloads may decrease after the unified content strategy is implemented.
§ Job obsolescence. Jobs may be reorganized, not lost.

Many of the challenges already mentioned can cause the project to fail. Resistance to change and lack of communication are probably the most common, but many others can also cause failure. Other challenges include trying to do more than your organization is capable of doing, economic factors, lack of core competencies necessary to complete the tasks, and various types of project mismanagement.

Role Creation/Modification
Many roles within the organization are subject to change as a result of the implementation of content management strategy. According to Rockley, two new roles will need to be created—an enterprise content coordinator and an informational technologist. The enterprise content coordinator will communicate the benefits of content reuse and will coordinate all different project managers’ reuse projects. The information technologist will handle all the technology tools and will supervise the implementation of those tools. Other roles with modified responsibilities include the business owner or analyst, the information architect, the content owners, the authors, sand the editors.

Barker chapter 13: Using Graphics Effectively

2007-04-23T15:15:00.000-07:00

In this chapter, Barker discusses how to use visual displays to the advantage of the end user. Barker promotes a liberal use of visual elements, so long as each visual is meaningful and useful to the user in some way. Therefore, Barker recommends using visual displays to accomplish the following rhetorical tasks:

Showing how the program’s tools apply to the user’s job
Showing the results of the program’s operations
Presenting an overview of the program so the user can understand when and why to use the program
Suggesting functions and uses of the program
Making abstract concepts into concrete images through metaphors (which can be extended throughout a document)

Visuals could certainly be used in other situations as well, but only if the visual helps to accomplish a rhetorical task. Avoid using un-cropped screen captures or excessively complex pictures that would distract or confuse the reader. Instead, cut all information that is not necessary to the user understanding the visual and its place in the document.

Barker assumes that his readers will already know how to create visual displays, so instead of discussing the process of producing a visual, he outlines some general guidelines for using and placing visual displays within a document.

1. Identify needs for graphics by your users
Visuals can be used to answer some common user questions: Where is something? What is something, and how does it work? How do I do something? Where am I in the program/document? What is the big picture?

Barker defines two types of visual cues that can be useful in answering some of these questions: access indicators and progress indicators. Access indicators tell the user where certain things are located in a document or program, and progress indicators tell the user where they are in the document or program. These can tell the user where something is, where they are, or what the structure of the program is.

2. set graphics styles
Consistency is next to godliness in the editing world. Set your visual standards early on and stick to them throughout the document. Many documentation programs have object styles functions built in to help with this.

3. revise and edit
Work with graphics after the text has been written. Barker promotes a balance of text and visual, so that one doesn’t overpower the other. The visuals should play a supplemental role to the text, to help the user retain information more effectively. Don’t let a visual act as a substitute for naming something.

Barker also makes several other specific points about standardizing graphic elements:

Not all images require titles, unless they are official visuals or copywritten
Labels are not always necessary, unless you refer to several visuals in the same chapter or section
Always place a visual as close as possible to the text that refers to it
Keep rules straight and of uniform size
Keep visuals within the margins, and crop out all unnecessary parts of them
Only use reserved colors (red for danger, yellow for caution) for their intended purpose

4. revise for typography
Here, Barker refers to visual typography as the arrangement and construction of the images based on a logic. This refers to the individual elements that make up the visual, such as color, emphasis, alignment, cropping, etc. Barker advises us to use the following methods to enhance the clarity and emphasis of a visual:

Make important things larger
Make important things darker
Make important things central
Make important things sharper
Align related things
Put first things left, later things right

Rockley Chapter 16 Summary - Becky and Jaya

2007-04-22T18:51:00.000-07:00

Chapter 16 – Content Management Systems
Rockley – Managing Enterprise Content
Jaya and Becky

Rockley discusses how content management is an integral component of a successful unified content strategy. To begin, Rockley discusses the basic functionality of the content management system (CMS). All content must be saved in order to be reused. The two parts to saving content are:
-Dividing the content into elements of appropriate sizes for the intended reuse
-Adding metadata to the elements to define them for effective reuse, retrieval and tracking.

The CMS also needs to be accessible for various projects and people and archives must be created to allow access to older versions and to track changes. There is also the issue of security such as controlling access to various authors and content users. Management functions such as access and version control are put in place.

The process of breaking content into element parts is called segmentation or bursting. The level of segmentation is defined in a segmentation or bursting map. Elements can be broken down to sentence level, but can also remain in larger section such as was given in the B-Brother product example on pg. 313.

The metadata can be applied to the content in the authoring tool or as the content is saved in the CMS. Rockley states that whenever possible it is good to have the metadata automatically applied to the elements of content. (Widget Y example on pg 315)

The next portion of the chapter discusses management controls such as: access control, check-in/check-out, and version control. Access control determines who can read, create, modify, and delete content. Check-in/Check-out is when authors who are working on content check it out and then check it back in when they are finished with it. This helps to ensure that only one person is working on it at a time. Version control means that every time content is checked in that another version is created and assigned a new version number. This ensures that every change is saved and can be tracked.

The three types of updates are:
Automatically update - automatically updates the reused element when the original element is changed.
Optionally update – The CMS notifies authors of the changes so they can decide whether they want to update the element or not.
No update – If the original component is updated, the reused element is not updated. Authors are not notified if the original element changes.

There are terms discussed such as:
Repository – heart of the content management system and manages the unified content.
Search and Retrieval – Important that this is dependable to assist authors in easily finding and retrieving content for reuse and delivery.
Archive – Content is archived based on set of rules that specify the period of time in which the content is considered valid or accurate.
Translation – There must be a relationship between the source language and the translated content in order to eliminate errors and save time.

The last part of the chapter goes over the various types of content management systems. Web content management is said to be the most familiar type.

Rockley - Chapter 11 - Designing Workflow

2007-04-14T18:49:00.000-07:00

Anne Peterson - April 14, 2007

What is workflow?

Rockley says that workflow, as it relates to content management, defines how people and tasks interact to create, update, manage, and deliver content. A properly designed workflow helps organizations perform tasks smoothly and efficiently.

Rockley says there are three components of workflow:

Roles (players)
Multiple people play different roles in producing, delivering, and storing content. Players can include authors, reviewers, editors, and approvers. The workflow doesn't tell players how to do their part. Instead, it tells them that they are part of the process, what that part is, and when their part must be completed.
Responsibilities (tasks)
A task is defined as a particular series of actions that accomplish a particular goal. There are several different types of tasks: tasks that add value (work tasks), tasks that move the task along ( transport tasks), and tasks that introduce a delay (wait tasks).
Processes (flow)
A process has a starting point and an ending point. Separate individual tasks must be completed between the beginning and end to reach the final goal.

Rockley says effective workflow is just common sense. It provides many benefits in the content management world, including the fact that:

Departments that should be creating content or be aware of it are included.
Content and supporting material are created in a logical order.
Content is reviewed at the proper time by the proper people.
Departments are notified when new content is published.
Duplicate efforts are eliminated.
Content is stored properly.

To create a workflow, you should review a process as it currently exists and then work to improve and simplify it. It is important to include everything that needs to take place in a process, but what should happen. Analyze, change, and test the tasks for a smooth sequence. It provides these benefits:

Greater efficiency - work is done more quickly and delays are eliminated
Better quality - authors can focus on their individual tasks
Lower costs - duplicate efforts are eliminated

How are workflows depicted?

Rockley suggests two formats for designing workflow:

Flowcharts - depicts a process in a linear format -- from beginning to end using symbols. There can be some frustration trying to read flowcharts if universally understood symbols are not used.
Swimlane diagrams - depicts processes in a lane format, showing tasks that occur concurrently, who does what, and when.

Rockley suggests that a workflow that will be supported by a workflow system should use the swimlane format.

How do business requirements affect workflow?

Each organization can make business decisions that affect how a workflow is used:

Budgets
Time dedicated
Union job descriptions
Physical locations
Suppliers

How should tasks be written?

Rockley recommends that tasks be written in a consistent verb-noun format. Everyone who reads a task should be able to understand it. Write tasks descriptively so they are not open to misinterpretation.

How is an effective workflow designed?

Determine a starting point, whether it is a new product or a crisis situation. If tasks that are not part of an automated workflow, indicate where the automated workflow starts.
Determine a place for the workflow to end.
Identify all the players from the beginning to the end of the workflow. A task should be associated with a role.
Sketch the tasks by identifying which tasks align with each player. Look for potential conflicts.
Identify interactions patterns among players and tasks.
Set timeframes for tasks and select an start and end for the entire workflow
Identify notification patterns.
Identify approval patterns.
Determine the "what if" scenarios that may affect the workflow.
Examine final workflow for simplification.
Repeat the steps for all the workflow processes needed to support the unified content life cycle.

Selecting a workflow system.

Rockley says that selecting a workflow system should come after the workflow has been designed. It is important to make sure that the system will do what needs to be done.

Rockley Ch. 10 - Erik Sorensen/Emma Baumann

2007-04-07T20:55:00.000-07:00

Managing Enterprise Content: A Unified Content Strategy

Ch. 10: Designing Dynamic Content

This chapter deals with the different ways in which content can be assembled to accommodate different situations.

*Personalization- Content is assembled to meet users’ specific needs.

*Systematic reuse- Content is assembled based on author requirements and business rules.

*Collaborative learning - Content is assembled to customize the learning experience of the intended user.

Basically dynamic content deals with the concept that content is created in excess each year and with so much information out there, there needs to be a way to deliver it so customers and users can pick out what they need. Dynamic content is not a substitute for well organized web sites and so forth but rather another way in which to make content accessible to a user.

Creating dynamic content is a very time consuming process in which sometimes the cons can outweigh the pros. Creating a specific user profile for each individual can also slow down the system because a lot of processing will slow down performance. There is an option to pre-build content based on a known configuration but there will always be instances when dynamic content needs to be created on the fly.

In order to support dynamic content you need to identify content user requirements:
- Identify your user needs
- Design metadata and user profiles
- Identify dynamic elements in models
- Define business rules for the assembly of dynamic content

Because the focus of dynamic content is to deliver the right content to the right user at the right time and in the right format you need to clearly understand your users’ needs. You may even create a persona which is the typical profile for the typical user.

Also, be sure to use metadata correctly in order to identify the correct content for the user. Examining the metadata will allow you to develop profiles which allow the users to differentiate and streamline the appropriate content for the appropriate group. Remember, user profiles are tied to logins and therefore when the user logs in they can see information that is only relevant to their needs.

User profiles that are effective are dynamic and change with the users’ actions. Just like the user learns from the software, the software can learn from the user by using personalization. The information that the software learns about the user can then be incorporated in to the profile and be accessible for the next time the user logs in.

It is also important to identify dynamic elements in models. The models ensure that the correct content is being dynamically assembled to ensure the correct content is assembled in the correct order and content. Models can identify which content is to placed in which section based on what role it plays.

Developing dynamic content also has retrieval rules. These rules help tell which content is displayed under what circumstances and to whom. There are three rules on which to base your business rules according to Rockley:
- Specific knowledge requirements
- Related knowledge requirements
- Permissions to view certain content
These business rules often rely on a “if this then that” rule. If something is true then specific content is displayed.

Systematic reuse uses a combination of business rules and user selection to determine which information is automatically reused. However systematic reuse aims more at making the authors’ jobs easier rather than allowing the user to find content more effectively and efficiently.

Barker Ch. 11: Laying Out Pages and Screens (Ahles/Hennis)

2007-04-06T16:58:00.000-07:00

In this chapter, Barker focuses on what he describes as “the two main elements of document layout: the design of the screens and pages and the design of type” (349). Overall, this is an important chapter to a technical communicator in that it gives them information on how to lay out their information. Barker goes through the aspects needed in a very simple, easy to follow format.

Guidelines
Barker first starts by giving the six guidelines for designing pages and screens, each containing important information on layout.

1. Review the User Analysis: When you’re going to be designing your layout, be sure to look back at the user analysis you’ve made. This will keep you on the right track.
2. Create Page Grids: This is basically providing a framework for you pages. Basically, you create spaces for all the text, images, headings, and margins that will encompass your page.
3. Define the Page Grid Using Styles: Styles can be an easy and efficient way to map your pages.
4. Draw Thumbnail Sketches: By drawing out the pages text, graphics, and headings in a small line picture, you can outline the proportions of your page. Barker recommends you fold a piece of paper into four-quarter spaces and use each quarter-space as one page.
5. Set up Pages and Styles in Your Word Processor: By saving your styles, you can ensure more consistency in your document. You won’t have to go back and retcon the styles you may have used.
6. Determine the Layout of Help Documents: It’s important to determine how your document’s overall layout will be put together. When making your sketches and styles, keep the overall document in mind.

Modularity
Another important concept that Barker brings up in this chapter is modularity, breaking information down into textual and graphic units to be fitted into one or two pages. For this, Barker recommends breaking down only one task per page. This page should contain all the information the user would need without referencing other tasks. To accomplish this, Barker suggests minimizing cross-referencing, repeating backgrounds, and keep all appropriate steps on one page.

Page Design
For the design of the pages, Barker brings up two kinds of formats: two-column and one-column. With the two-column, the page is divided into a column for text and a column for graphics. In this single, both text and graphics are put into one column. Other elements of page design include:
The Left Margin
Columns
Headers and Footers
Icons and Diagrams
Screen Shots
Rules
Pagination

Guidelines for Developing Instructions - Chapter 8

2007-04-03T20:55:00.000-07:00

In Chapter 8, the authors lay out their suggested procedure for preparing instructions; we might call this chapter meta-instructions (instructions about instructions.)

Their six-step procedure for preparing instructions includes the following: (1) set ground rules, (2) gather source materials, (3) conduct analysis, (4) design, (5) write and edit, and (6) conduct user test. The chapter consists of an explanation for each of these steps.

The first step is to set the ground rules. Technical responsibility is laid upon the Subject Matter Expert (SME), while writing and presentation are left up to the writer. Trouble brews when some of the burden of writing is placed on the SME, with no compensation to go with the extra burden.

Responsibilities:
- Technical Accuracy: SME is responsible for providing source documents, and reviewing resources for accurate information. Problems can arise if the writer attempts to act as their own technical expert.
- Technical Content: Responsibility is shared.
- Schedule: Depends on the deadlines; however, sufficient time should be given to both the writer and SME to ensure enough time for creation and reviewing documents is given. If one party is late, the other party should not be penalized..
Define Users
- Literacy Levels
- User Familiarity
Constraints
- Graphics: Graphics are possibly restricted or even banned from use; this makes creating documents difficult.
  - Sometimes writers are not informed of restrictions until the project is well under way.

The second step is to gather source materials. This can be complicated, especially if the company doesn’t have all that much data to spare; sometimes, all they have is engineering illustrations and assembly instructions. A part of the writers task is to seek out information, often interviewing engineers to do it. Data to look for includes:

• Instructions for previous models

• Engineering drawings and specifications

• Line drawings

• Task analysis data

• Test specifications

• Photographs or videotapes of the product in use

• Product specifications

The third step is to conduct analysis. This can be accomplished by someone simply observing while a SME demonstrates the tasks. The primary goal of analysis is to see if there is anything safety related that should be included.

The fourth step is the design of the instructions. At this time you will select the media, format, and layout. You will also determine what the rules will be for developing the instructions.

The fifth step is the writing and editing. This is the process when you take data and instructions that you have compiled and analyzed, and place it in tis final format. Limit your usage of verbs. After completing the first draft, walk through the steps mentally. Editing consists of basic quality control.

The sixth and last step is to conduct a user test. Have two or three inexperienced subjects perform all tasks, with no prompting from the writer or SME. Keep in mind this is a minimum; the more people you test with, at varying levels of experience, the more likely you are to detect problems before going on to mass production. When changes are made, especially major changes, retest to make sure you have solved the problem.

Inaba Chapter 9 - Becky and Jaya

2007-04-01T13:46:00.000-07:00

Chapter 9 – Special Considerations for Maintenance
Guidelines for Developing Instructions
Becky and Jaya

The last chapter of this book pertains to the special considerations for maintenance. The authors discuss the inherent structure is based on the fact that maintenance is made up of a common set of functions (checkout, align, adjust, etc.) and each function is made up of similar tasks. Because of this, the total set of maintenance tasks required can be defined for most systems by a matrix functions applied against the equipment at different levels of detail.
The maintenance functions defined in this chapter are: adjust, assemble, calibrate, checkout, disassemble, inspect, install, remove, replace, repair (in place), service and test. The authors talk about the use of these various terms such as remove and install are usually treated together and is sometimes identified as replace.
An example of a matrix system is given. The left column details the systems and equipment units included in each system. The other columns are the maintenance functions. The entries in this matrix identify the maintenance tasks required for each system. The authors discuss the hierarchal structure of the equipment and how to read the matrix.

Special troubleshooting analysis, Failure Mode and Effects Analysis, is discussed as a well-known analysis approach which is normally reserved for systems with potentially hazardous consequences for malfunctions. It is not used often due to being labor-intensive requiring extensive participation of engineers which adds considerable costs. There was an adaptation to this process in which the labor effort required can be adjusted by selecting the level of analysis used for the selected portions. This adaptation was called the Failure Mode and Indications Analysis. This project was considered a major factor in the development of a maintenance system that contributed to extending the operational life of a system. The process consisted of:

- Develop a list of components
- Develop a list of indicators (of system failures)
- Identify the modes of failure (of each component)
- Trace the effects of failures to indicators.
- Summarize the modes of failures by indicators
- Develop diagnostic procedures

The last portion of the chapter details the format for troubleshooting instructions. The most common choice for presenting troubleshooting instructions is the Symptom-Cause chart, which is organized by symptoms and list probable causes, and the checks required to qualify the probable causes. The other choice is logic diagram which presents a network of checks and results that lead to corrective actions and is also organized by symptoms. There are examples of each given at the end of the chapter.

Chapter 7 and 8 Barker

2007-03-31T20:28:00.000-07:00

This chapter was called Conducting Usability Tests. The chapter went over 3 basic types of tests:

1. tests for task performance (procedures)
2. tests for skill and understanding (tutorials)
3. tests for access to information (references)

- Hide quoted text -

The first step is deciding when to test. You can usually test at about 3 stages-- during design, during writing and development, and after the document set goes to the customer. Then you must select the test point. A test point is an issue or feature of a document that might interfere with the efficient and effective application of a program to a user's work activities. Then to select procedures for testing, you identify what issues you want to test by determining a point in your documentation where there is a chance for user error. To select design strategies for testing, look at terminology (language), an index (for consistency), cuing patterns, headlings/layout, navigation, and extraordinary document formats (special conditions). Next, you must choose the type of test to use. Relating to test points of tasks, terminology and document design strategies, you can use the Can They Do It Test, Can They Understand It Test, and the Can They Find It test. You may have to use more than one test.
Setting performance and learning objectives is important because you want the tests you perform to measure real behavior. Good performance does not necessarily mean getting something done in a short period of time. Kinds of performance objectives include

* time-related - time taken to perform a procedure
* error-related - Number of errors made during a procedure, number of times a passage gets reread before comprehending, and number of tries in the index.

Objectivity in testing means setting up the test in an unbiased way as to ensure the test does not just pass automatically to let you get on with the project. You cannot let personal bias to get into your test.
Selecting testers and evaluators is the next step. The tester is the person who administers the test: arranges the meeting with users, sets up the test situation, records the test activities, and so on. The evaluator is the person taking the usability test. Then, prepare test materials and know how you want to use them. There are many kinds of test materials, including:

* Evaluator Selection Survey - A brief list of questions that potential evaluators fill out to ensure they meet the profile as typical users.
* Instructions for Evaluators - A one-page list of instructions to help evaluators understand their role.
* Test Schedule - Schedule of testing times and locations for tester and evaluators to follow.
* Instructions for Testers - Set of instructions telling the test monitors how to conduct the test and how to record information.
* Test Lab Procedures - Set of instructions for operation the testing facility.
* Pilot Tests - Mock-up versions of test forms to try out as a way of determining how well the test works and the suitability of the performance objectives
* Test Forms - Actual tests written up as test scenarios, task descriptions, and/or procedures.
* Test Subject Materials - Actual copies of documentation that the test intends to evaluate
* Software Overviews - Marketing or overview information that informs evaluators or the main uses and features of the documentation they will use.

Kind of hardware and software test materials include a tape recorder, notebooks, camera, intercom, tables/chairs, and timing clock. All these items are used to test and simulate the actual working environment. Setting up the test environment can be a difficult task, as there is no perfect place to do this. The user's workplace, a lab, or a combination of the two. The latter two are the more expensive choices, but the user's workplace is intrusive.
Make sure information is recorded accurately. This way, you can evaluate and interpret the data to come out with a solution that best fits the user.

Chapter 7 - Writing Software Documentation - Barker

This chapter discusses getting useful reviews. To begin, Barker says a reviewer guidelines transmittal letter should accompany the document. This sheet gives document background, kind of information writer needs from reviewer, where to send mark-up copy, clear instructions for mark-up and encourages partnership with writer.

Barker details the following as guidelines for managing document reviews:

* Review the document objectives from the document plan.
* Determine the type of review needed.
* Establish a review schedule.
* Plan the review.
* Write a cover letter with questions for reviewer.
* Prepare feedback material for reviewer.

There are different types of reviews that require different people to be involved who will have different concerns regarding the review. For example, a managerial review involves managers, supervisors and team leaders who are concerned with staying budget, meeting objectives and quality control. All reviews can offer challenges and problems as all are not on-site and may not be familiar with the project. By establishing a review schedule, some problems may be eliminated.

Barker also discusses the advantages of sequential circulation verses simultaneous circulation. The writer would need to figure out which works best. The cover letter provides the following objectives and benefits to the reviewer: request for specific advice and comments, necessary background, tell reviewers how to mark or comment, give date and place for return, thank reviewers. The writer should also provide feedback materials.

Barker distinguishes between reviewing, testing and editing. Reviews require comments from several people whereas testing concentrates on users and issues of accuracy and statistics, and editing comes from trained editors who perform various levels and types of editing to your document. Barker states that reviewing is critical throughout the documentation process stages; planning and design stage, user analysis stage, development and writing stage and the draft stage. It is important to remember that all the document changes should be negotiated diplomatically. The different cultures from within a company may bring different perspectives as to how the document should look.

To conclude, Barker suggests a user walkthrough in which you present the document from beginning to end and focus questions on the key issues of usability. This review will contribute the most to helping meet the task needs. During a user walkthrough the information illustrated can only come from actual users.

Examples of questions are:

* Does the document reflect recognizable workplace activities?
* What tasks does the document not focus on that users would find important?

2007-03-31T19:21:00.000-07:00

Case/Pass
Barker ch 10

Barker discusses document design and its obstacles in chapter 10. He covers issues such as meeting user needs, how to accommodate specific user groups, as well as the different tools available for writers.

Fist we are given ‘Guidelines for Designing Documentation’

1. Create a table of contents
a. This can help a writer organize their document as well as assist the user in many ways
2. Match the user analysis with information design strategies
a. Design for different groups
b. Design for specific program issues
c. Meet user task needs
d. Meet user information needs
e. Match user computer experience
f. Enhance user’s subject-matter background
g. Leverage the user’s workplace
h. Meet the user’s learning preference
i. Meet the user’s usage pattern
3. Acknowledge production constraints in document design
a. This is where writers evaluate what the want versus what they can do
4. Test and review the design
a. This is best done with a form of usability testing
5. Follow a design process for online help
a. Online help uses topics
· About
· Module
· Action
· Problem
· Question
· Task
· Update
· User Group

The next part of chapter 10 deals with the Design Problem. In short, this is when the writer attempts to accommodate many users with one format. This is especially difficult in print because users’ search abilities are limited. To help remedy this problem the writer must first categorize his users. This can be done in multiple ways; two the book suggests are using computer experience or level of professional use. After the groups have been identified, the writer can then begin to analyze the users’ problem solving methods. Some points to keep in mind when doing so are:
1. No one reads carefully so keeps things short and accessible
2. Most users do not read the entire manual, instead they do specific searches when the run into problems.
3. Users wait until the have failed a task to look for help and are often impatient at this point.
4. Most readers do not bother reading introductions because they feel they are not related to user needs
5. Most users do not read any one section in its entirety; instead, they filter information while scanning.

After looking at the issues writers face when accommodating to their audience, Barker offers us an overview of the tools available to writers as well as a brief summary of how they are best used. Some of the design tools he referred to were
· Navigation
· Cross references
· Running headers and footers
· Layering
· Headings
· Advanced organizers
· Document overview
· Parallel structure
· Cuing
· Bookmarks
· Histories
· Pop-ups
· Links and jumps

Nelson and Haupt - Rockley Chapter 9: Metadata

2007-03-31T07:57:00.000-07:00

Metadata is “data about data.” Any item of data is a description of something. Metadata is a type of data where the something being described is data. There are two types of unified content metadata: categorization and element. Users tend to use categorization to search for metadata, yet authors will most likely us an element search to find metadata.

An example of metadata would be to recognize a date on a photograph then when later searching for that practically photograph a user could search for the photograph by the date on it.

when compiling metadata it is important to understand who is going to retrieve the content, what tasks are they trying to accomplish with the content, and what terms will they use when retrieving the content. After understanding the first three steps in creating metadata it is important to create taxonomies. A taxonomy is the grouping of like or similar content together. After you have grouped your taxonomy you will want to test it. To test the taxonomy you will want to run a usability test on it.

When working with element metadata there are three main types: reuse, retrieval, and tracking metadata. Reuse is if data already exists in a data base then the metadata will recognize and ask the user if they would rather go back and reuse the data in it. Retrieval metadata is used to help authors retrieve content and information. Examples of information in a retrieval metadata would be the title/ subject, author, date, and keywords, and the security level. Metadata for tracking is used when showing workflow.

Metadata needs to be consistent to facilitate reuse, retrieval, and tracking. To keep metadata consistent it is best if a controlled vocabulary is created.

Rockley Chapter 9 - Designing Metadata (Peterson)

2007-03-27T08:55:00.000-07:00

I apologize that I didn’t post this weekend. Totally misread the reading assignment chart.

Metadata can be looked at several ways. The short definition of metadata has often been described as “data about data.” Rockley expands that definition to include the importance of how data can be used for effective search and retrieval, reuse, and dynamic content delivery within an organization.

This chapter discussed the levels and different types of metadata that are needed for a successful content strategy. Rockley says that metadata enables:
• Effective retrieval
• Systematic reuse
• Automatic routing based on workflow status
• Tracking of status
• Reporting

This requires proper defining and categorizing of the types of metadata used.

Benefits of Metadata
• Reduction of redundant content
Consistent labeling of content enables authors to easily retrieve existing, reusable content. It also can identify situations where duplicate content might be created if multiple authors are involved.
• Improved workflow
Tagging content with metadata identifies its status and workflow automatically manages the content.
• Reduced costs
o If content already exists and can easily be retrieved, the work required to recreate it is eliminated.
o It can also help determine when source elements have changed. If set up properly, metadata can ensure that the changes are automatically populated everywhere it is used.

Types of Metadata
There are two types of metadata – categorization and element.
Categorization
Rockley described categorization metadata to be similar to the card catalogs and Dewey Decimal System used in libraries. Corporate information needs to be just as accessible as library materials. This is achieved with metadata hierarchies and metadata taxonomies. A hierarchy provides the content user with an understanding of how content is organized and the same content may be organized under more than one category. Metadata taxonomy is categorized in only one place.

Categorizing content can be difficult and time-consuming. It can initially involve a lot of manual work. Standards must be put in place. Some industries have developed vertical taxonomies that can be applied. Some vendor tools are being created to help with the process.

Rockley says that it is important to understand users when developing categorization:
• Who is going to retrieve the content?
• What tasks are they trying to accomplish with the content?
• What terms will they use when retrieving the content?

To create a taxonomy:
• Group or cluster related content
• Develop taxonomy – each term becomes metadata
• Test the taxonomy – ask users to perform a usability test

Element
Authors use elements to help manage content. There are three main types:
• Reuse metadata – identifies the components of content that can be reused in multiple areas
• Retrieval metadata – helps authors retrieve content and may include much or all of the reuse metadata, but it is more detailed
• Tracking (status) metadata – helps with implementing workflow.

Creating a Controlled Vocabulary
Consistency is critical for the successful use of metadata and a controlled vocabulary goes a long way to achieving this, especially if authors are creating their own metadata tags.

Ensuring Metadata Gets Used
Metadata is valuable only if it is used. Rockley suggests that an organization automate as much of the metadata application process as possible. That helps to ensure that metadata gets used and helps authors add metadata in the authorizing tool, rather than as it is checked back into the system.

Late Posting

2007-03-26T18:25:00.000-07:00

Jaya and I have not yet posted Guidelines for Developing Instructions, Chapters 7 and 8. Our apologies. We will attempt to have this posted by Sunday evening.

Becky Guadagnoli

Barker Ch. 9 (Erik Sorensen & Emma Baumann)

2007-03-25T10:00:00.000-07:00

Barker Chapter 9
Editing and Fine Tuning
Summary

By Erik Sorensen & Emma Baumann

This chapter is concerned with the editing and revision of projects as a management concern. The chapter offers guidelines to help develop a consistent and efficient style of editing.

1. Establish Project Guidelines
It is often important for the writer or writers of a document to be on the same understanding. This will help to ensure that goals and objectives of given documents are met. It is important in this step to identify your audience and make sure all editing is done with the audience in mind. Sometimes editing is done by other people and sometimes the creator of the document will edit it themselves. In each case it is important to be consistent and ensure attention is paid to detail. Barker introduces editing marks that seem to be universally understood so that editing can be done collaboratively.

2. Understand the Types of Editing

These are sometimes called levels of editing. There are four basic types of editing: Managerial, Substantive, Copy and Proofreading. Each one of these edits is unique in its intention.
Managerial editing concerns itself with the documents and their planning rather than the actual format and content. This type of edit will require comparison to other management materials. This edit will be done by managers and editors from a group working closely with the writers of the document.
Substantive editing involves editing language and information. This edit is done closely with the author and deals with the structure of the document. Substantive editing deals a vast amount the following are some examples:
Organization
Fluency
Parallelism in steps
Clarification
Omission
Copyediting will deal with grammar, mechanical style, and format. This editing will take place in the latter stages and most of the groundwork has already been laid. This would be like how we use to edit each others papers in high school. You will be looking closely for silly mistakes and final touches such as spelling, subject/verb agreement, acronyms, abbreviations and so forth.
Proofreading is the last stage. This will be an overall check of the document. You may catch mistakes that were previously undetected. This is the last opportunity to catch mistakes before printing takes place, so look closely!

3. Plan Your Editing Tasks
Planning your editing should take place at the very beginning stages of a project. This will allow for the best situation for proper editing to take place. Scheduling editing will budget the necessary time initially. However, there is no definite rule on how much time should be allotted for each step. Barker provides a rough guideline for each level of editing.

Managerial Editing: 10-15% of all activities
Substantive Editing: 6-8 hours per page
Copyediting: 1-3 hours per page
Proofreading: 5-10 pages per hour

Each level will require different tasks of the editor. For example, in a managerial edit you should plan on attending meetings and communication is the key on this level since you will be working closely with all aspects of the revision. Substantive editing will require you to look at each page of the document as its being created and closely keep in mind the readers needs. You will also be checking style and again, the meetings for comments and suggestions. Copyediting only requires one session per draft and will be done after the document is complete in draft form. Proofreading is just a matter of double checking things however; it can be extremely tedious so more than one person may be essential and beneficial.

4. Develop the Appropriate Editing Forms
Often times in order to save time and energy a company may have existing forms and procedures for editing. This can help regularize procedures and streamline the process. One of the most important forms, according to Barker, is a style sheet. A style sheet is a sort of way to keep track of the revisions as they happen. This is not to take place of a style guide but rather allows you to keep track of the small changes as they occur.
A style guide will contain all the rules and conventions for a specific project. This is a way to keep things uniform throughout a department or company and can also set a standard for future documents. A style guide does numerous other things and is essential for any project.

5. Conduct Editing Sessions
Different edits can occur at different levels of the document life cycle, however there some general rules that apply to each edit. Editing requires concentration so distractions are not encouraged. A checklist is also beneficial, especially if you are editing your own work in order to avoid ignoring our mistakes. There are a few other tips offered: edit with a partner, shorten editing sessions.

Managing Enterprise Content ch. 7 (Ahles/Hennis)

2007-03-15T07:02:00.000-07:00

Chapter 7 continues Rockley’s idea of the unified content life cycle that was introduced in Chapter 5. Here though, Rockley talks about how the content life cycle can be put to better use in making a more efficient unified content strategy to aid your organization. Before you can begin your content strategy though, Rockley says that you must “identify organizational goals and issues, examine your current content life cycle, and analyze your existing and published content to determine potential reuse" (127). Doing all of these tasks will help you gain a better idea of how your content strategy can be improved on, and how these changes can be done through the proper utilization of a content life cycle.

Addressing Issues
At the beginning of the chapter, Rockley talks about the kinds of issues that need to be addressed with the content life cycle. Identifying these challenges should be the first step in your project and could be any number of things within your organization. The issues that Rockley gives fall into six categories:

Content use
Content authoring
Translation
Global requirements
Review
Publication and delivery

For each of these issues, Rockley gives required steps to addressing the issues, and which life cycle phase the issues can be resolved in. For example, the Content use issue of too much detail/too little detail should be dealt in the Create phase and can be resolved by re-evaluating the requirements and rewriting material accordingly along with providing content that is specific to the user’s needs.

Another example would be the issue of authors not being able to find the information that they need. An answer to this would be storing all content in a single repository, one place where the authors can find all the information that is available on a single product. Another response would be developing a better categorization method for the author to find the information. These solutions would need to be developed in the Manage and Create phases of the content life cycle.

Life Cycle Samples
The last half of the chapter gives two samples of how a unified content life cycle works for two companies: CreateSoft and Envigor. Both companies have issues with their produced content and decide to implement different strategies. Envigor decides to switch to XML for more control over their content and ensure a more consistent product. CreateSoft, though staying with their existing authoring tools, decide to try a new management system to manage and distribute their content. Rockley goes into each phase of the respective companies’ plans and talking about the differences between the two. For example, in the area of check-in content in the Review phase is handled differently. Envigor is automatically notifying a reviewer when content is ready for review while CreateSoft manually routes the content to reviewers.

Guidelines for Developing Instructions, Chapter 7 – Nelson and Haupt

2007-03-07T05:57:00.000-08:00

The authors present a concise style guide in Chapter 7. Recognizing that there are many possible variations in style, Inaba, Parsons, and Smillie “suggest you use the specifications in a flexible manner and try not to adhere to them rigidly or unthinkingly.

The text offers guidelines for the use of Headings, Command Steps, Sequence of Tasks and Steps, Callouts in Text, Subprocedures (Procedures within Procedures), Table to Supplement Instructions, and Guidance and Routing Information (Notes)

The reference to ANSI standards on page 80 is particularly helpful. The two main ISO/quality organizations in the United States are ANSI and ASQC. The American National Standards Institute (ANSI) is the United States representative to the International Standards Organization (ISO). The American Society for Quality Control (ASQC) is an organization that develops, promotes, and applies quality-related information and technology for the private, government, and academic sectors.

Adherence to official and de facto standards is critical in technical communication. There are a multitude of national and international standards-setting bodies in addition to ANSI and ASQC. For example, The IEEE, a non-profit organization, is the world's leading professional association for the advancement of technology. The full name of the IEEE is the Institute of Electrical and Electronics Engineers, Inc. It is the IEEE that sets many of the standards that today’s computer systems utilize. For example: 802.3 (Ethernet), 802.5 (Token Ring), 802.11 (b) and (g) (Wireless Ethernet).

Due to the existence of numerous standards bodies and the potential for conflicting quality standards, the ISO created a set of five (9000-9004) standards developed to help harmonize the large number of national and international quality system standards. The ISO standards (conformance models) are themselves a subset (in the United States) of the Malcolm Baldridge National Quality Award Criteria. Gaining a working knowledge of standards applicable to the technologies you are working with is invaluable. As you gain an understanding of the standards, you will yourself become technical, and will be able to converse intelligently with the engineers involved in your documentation projects.

Following is a comprehensive listing of the rules Inaba, Parson, and Smillie suggest technical writers use when creating documentation:

Use distinct, obvious headings to help the user quickly identify and locate the instructions, as well as all of the sections or parts of the instructions.

Place headings that identify jobs or tasks flush with left margin.

Place headings for Notes, Cautions, and Warnings in the center of the column

Use consistent amount of space between heading and subsequent text (e.g. double space).

Set all headings in bold with consistent use of upper and lower case.

When instructions exceed one page, repeat task headings at the top of each page.

To compose titles for tasks and task sequences (e.g., jobs) use the command form of an action verb or verbs followed by the name of the system, equipment, or other objects of the action.

Use a simple, fixed syntax for command statements. Use a transitive verb (one taking an object) from the command verb list, followed by one or two objects.

In necessary, modify verb or object with one or two prepositional phrases of a dependent clause. Place such phrases after the basic command.

Use conditional phrases and clauses to tell how, when, or where to accomplish the work. Please such conditional phrases and clauses before the basic command.

When the actions are identical for a number of clearly related items treat the entire set as a single action.

Use fixed set of nomenclature for objects of action verbs.

Use a maximum of three obviously related actions per step unless a fourth action is needed to bring the step to a close.

If a single action produces a clear and specific result, and requires more than 30 seconds to perform, present it as a separate step.

Limit the total number of words in a step to 25, except when additional words are presented in list form.

Use only one command verb per sentence, unless two verbs are needed to express alternate actions or actions taken close together in time.

When a command sentence requires more than two objects, present the objects in list form following a colon. If the list is greater than four, partition the list into groups with no more than four objects in a group.

Assign an Arabic number to each step. Assign 1 to the first step in each task and assign numbers in proper counting sequence to the subsequent steps.

Arrange tasks and steps in a task in the most likely order of occurrence.

Incorporate instructions for the use of special tools or test equipment in the sequence if the use occurs only once or twice throughout the entire set of instructions, and no special skill is required to use them.

When extensive routing is involved within a task (e.g., from two or more steps), provide a routing page that serves as a road map for the user and supplements or is supplemented by the detailed instructions.

Place the appropriate callout number in parentheses immediately following the name of the equipment.

When there are two or more like items on the graphic, use two or more callout numbers with a single noun.

As an option use a subprocedure when a short sequence has a clear and specific result, is needed as part of different tasks, but is not long enough to merit being treated as a task. Compose the title as a step, add “as follows:” and list the action.

Use tables in combination with command steps when they help clarify instructions. Tables are useful when combinations of events or equipment are involved.

When using a table for routing purposes, insert the table immediately after the step and on the same page (or facing page) as the step.

When a large table is needed to support steps on several pages provide the fable on a foldout page that the user can pull out and use together with the instructional pages.

Assign numbers to tables when two or more tables appear on a page or on facing pages.

When using a table with a graphic to show the location and function of a number of similar items such as fuses and circuit breakers use callout number to link the items in the table to the graphic.

Use Notes to provide guidance information and to route the user to the appropriate instructions.

Always precede safety information with a Caution, Warning, or Danger heading, preceded by the safety alert symbol. Use multiple paragraphs if information exceeds 25 words or covers different subjects.

Place safety information entirely on the same page as the command step to which it applies. If this is not possible due to the length of the safety information or the length of the step, place the safety information on a separate page preceding the command step.\

Always place a safety alert symbol and a signal word immediately before the command step to which it applies.

If Danger or Warning and caution apply to the same step, present the Danger or Warning before the Caution. If a Note is needed, place the Note after the Caution or Warning.

Use the same style of heading as the style chosen for the planning page. Place the heading in the center of the column.

Provide explanations for the Warning or Caution, after the primary safety sentence.

For Cautions and Warnings, use strong terms.

Whenever a serious situation is implied write the primary safety sentence in command language.

When a Caution or Warning applies to two or more steps start the statement with a phrase to that effect.

Always place guidance Notes before the command steps to which they apply.

Present the routing information as a separate paragraph, separated from the preceding step by an empty space and with each alternate route in a separate paragraph.

Whenever possible shorten the description of the second alternative when it is the direct opposite of the first.

To help alert the user, include a phrase in the routing statement to describe the work to be done.

When directing the user to a step preceded by a Warning, Caution, or Danger signal word, or a Note, instruct the user to read the applicable information.

If the same obvious alternative applies to a series of steps place the routing statement before the applicable step.

Writing Software Documentation - Chapter 6

2007-03-05T08:27:00.000-08:00

Writing Software Documentation

Chapter 6

This chapter was involved with planning and writing documentation. This process has been divided into nine steps.

1) Start The Project – In the old days, one writer could sit down with a program and figure it out for himself. This is no longer the case, and most documentation is done in teams. A Development Team is composed of the programmers who created the software, while a Writing Team is made up of just writers.

2) Perform User Analysis – In any situation with giving directions, it is good to know how much your audience already knows. The purpose of this step is to ascertain that.

3) Design Documents – Form a template for how the help system will look and work. Do this for a tutorial, procedure, and reference in mind.

4) Plan the Documentation Project – Form a timeline for who does what and when.

5) Write the Alpha Draft – This is a preliminary version of the documentation.

6) Conduct Reviews and Tests – Make sure your documentation is on target.

7) Revise and Edit – Standard writing procedure.

8) Write a Final Draft – Again, standard writing procedure.

9) Conduct a Field Evaluation – This is when you go out and make sure Johnny Enduser is able to use your documentation effectively.

There are two primary development plans:

1) The Waterfall Method – One stage comes after another, and one cannot begin until the previous one has been completed. The easiest method to start up, it is also the least efficient.

2) The Rapid-Development Method – Writing and planning happen independently of each other; one portion of the team focuses on user needs and proper format, while the other focuses on the raw text required. Once a format is decided upon, the text is absorbed into it. Far faster to implement than Waterfall Method, Rapid-Development also calls for a higher team-work capability.

Summary - Guidelines for Developing Instructions

2007-03-04T15:11:00.000-08:00

Team 3 - Bynum & Peterson

Chapter 6 covers the use of both command and non-command verbs in a set of instructions, as well as nomenclature, nouns, pronouns, and the other parts of speech, including punctuation and symbols. Inaba also adds a list of command verb followed by a list of their definitions. Throughout the chapter, Inaba states rules, such as a topic sentence for the following paragraph. These rules cover everything from use in one statement to use in the whole document. Most of the rules are followed by a paragraph, and sometimes an example, which further explains the rule. Most of the rules in the chapter revolve around one basic principle, keep it simple.

Most of this chapter was already common knowledge to myself but I wish I had read it before doing the Quick Start Guide because I'm sure that the guide could have been done better.

(Since I still don't have the textbook, Matt took on the responsibility for writing the entire summary for this week's chapter. - Anne)

CHapter 6 Rockley

2007-03-04T11:33:00.000-08:00

Managing Enterprise Content, Chapter 6: Performing a Content Audit
(Case/Pass)

In this chapter, Rockley discusses a strategy for performing a content audit. Rockley defines a content audit as “an accounting of the information in your organization,” though the process could be described more specifically as an analysis and categorization of all the content present in your organization. Rockley identifies several steps in the process of a content audit, which include:

Identify the scope of the audit
Select representative materials
Analyze the content
Build a reuse map
Identify opportunities for reuse
Summarize your findings and document recommendations

Identifying the scope of the audit
The first step of a content audit is to decide what to audit. Most technical publication groups start with their content, and discover in the process that much of their content resembles what marketing or PR is producing. This will drive them to expand the audit out into other departments or groups to improve consistency. Rockley advises us it isn’t necessary to start big and analyze every department we can, but by starting too small, a decision could be made to use small or inflexible technology choices that won’t translate over if the decision is made to do a large-scale audit.

Selecting representative materials
This step is similar to taking a core sample of a group; it asks us to select several pieces of content from within our scope to represent the whole. Because a content audit is a comparative exercise, content that spans across the entire scope of our audit should be selected

Analyzing the content
Rockley recommends a method of breaking down each document into ‘pieces’ and observing where pieces of different documents are very similar or identical. Rockley splits this step into two parts: the top-level analysis and the in-depth analysis

A top-level analysis involves a scanning of the content for pieces of information that might be similar. Look for headings, sections, tables, graphics, product descriptions, introductory information, procedures, etc. Scanning the table of contents (if there is one) can be helpful in finding where information might repeat.

An in-depth analysis involves delving into the pieces of information that you identified as similar during the top-level analysis. During the in-depth analysis, we should identify which parts of the content are similar, which are different, which parts can be changed to become similar, and which parts could be standardized for reuse. Be sure to create some sort of system for yourself to track which pieces you identify as reusable, such as a table or a highlighting/marking system.

Building a reuse map
After performing an audit, it’s a good idea to map out findings. A reuse map is a matrix chart that identifies what content is reusable, where the content is reusable, and what type of reuse should be made. You can build a reuse map by assembling a table with your representative materials in columns and the content pieces you identified in rows. Where the pieces match up with their representative materials, you can place an identifying symbol for which type of reuse can be made.

Summarize your findings/document recommendations
Since single-sourcing could be a costly and time-consuming project, it is a good idea to write up a summary and recommendation report, because you may be pitching your ideas to higher-ups to get approval to go ahead.

Usability issues
In addition to saving time and money, a content audit might have secondary benefits as well. As you are scanning through your content, you might come across problems or inconsistencies that hurt usability and create confusion (for example, two identical procedures with different steps for completion). Content reuse is one method of eliminating those problems by making everything unified.

Writing Software Documentation, Chapter 5 – Nelson & Haupt

2007-02-24T05:48:00.000-08:00

Barker’s Chapter 5 informs us on the importance of the research phase of analyzing documentation users. Analyzing user research should be done with interviews, questionnaires, and surveys, either choosing to do one of the research types or all three. When analyzing the users it is best to focus on the eight areas of; tasks and activities the user will perform, user’s informational needs, users work motivations, level of the user’s computer experience, knowledge of the program’s subject matter, community, learning preference, and the user’s usage patterns. Try to immerse yourself into the workplace world of your users, list as many types or groups of the users as you can. Which users would most probably use the program and which users can be interview most easily.

Keep in mind the importance of sensitivity to the culture the users comes from and their nations or workplaces. When analyzing a user it is important to know that you may need to get authorization to interview people in the workplace. Pay particulate attention to information related tasks like communicating, storing, and sharing.

Barker points out to analyze the users before and after tasks by noticing small facts about the users, their attitudes and habits. Look for items such as notes stuck to bulletin boards, diaries of skills, or third-party computer manuals that the users employ in their daily use of existing technology.

In some instances a mock-up of the user or a model may need to used to perform the research. Barker suggests the use of library occupational guides, placement services that college or university use, or even job descriptions found in publications put out by companies.

Remember that deadlines and timeliness of reports often are what makes documentation useable or not. To help out in the research the use of a flow diagram may help to better clarify how the users' tasks are being accomplished.

When planning to do research Barkers suggests following some general steps.

Research into the user’s job and the programs.

Review the software..

Establish the scope, how many, with whom, etc..

Make a list of interview questions..

Get permission..

Set a schedule, date, times, and places..

Follow up, thanks you letters, reviews, and testing..

Techniques for Analyzing

Shadowing, observe the user by spending time at the workplace watching the users perform their jobs and tasks in addition to interviews and questionnaires.

Getting involved, don’t let the user know what you want to happen ahead or time because you may run the risk of chancing what happens naturally.

Barker mentions the use of cultivating a relationship with the users. What Barker does not mention is that if not done correctly then having a relationship may alter the research being done.

Chapter 5 describes the process of performing a user analysis as the initial stage in creating software documentation.

The user analysis is divided into eight categories:

Tasks and activities the user will perform

User’s informational needs

User’s work motivations

Level of the user’s computer experience

User’s knowledge of the program’s subject matter

User community

User’s learning preference

User’s usage pattern

The procedure for conducting a user analysis also consists of eight steps:

Choose users carefully

Anticipate transfer of learning: study users before and after using a program.

Research professional behaviors

Write use cases

Plan interviews carefully

Involve users in all phases of the project

Identify document goals

Tie the user analysis to document features

Each of these steps is described in detail in Chapter 5. It should be noted that the process described in this chapter is applicable only to large-scale documentation projects. The level of detail required has a direct relationship to the complexity level of the software application. Small projects will still require the technical communicator to perform a user analysis but it will be scaled back in scope and detail.

On large projects the technical writer is part of a dedicated writing team. This team normally consists of a manager, lead writer, writer, editor, graphics designer and test. The writing team works with the development team. The development team is usually composed of a project manager, software developers, market/systems analysts, technical specialists/programmers, and a documentation specialist. Additional information on these teams is found in Chapter 6.

It is common for the writing team to simultaneously develop documentation for multiple publishing formats. These can include hardcopy, PDF, online (HTML and XML), help systems, and localized (translated) versions of the documentation.

The user analysis phase of a project can last for months. During this time both the development and writing teams have extensive interaction with the user community. In the case of single source documentation projects the user analysis phase can become a development project all of its own. This is because actual document analysis must be performed to accurately describe the logical structure of different classes of legacy user documentation. Once the structures have been defined the development and/or writing teams will code those structures into XML/SGML schemas and/or Document Type Definitions (DTDs). Of particular interest is the fact that if Framemaker will be used by the user community then an additional step is necessary. The DTDs will need to be translated into Framemaker Element Definition Documents (EDDs). The EDDs merge logical structures with typographical markup. Thus, a user creating documentation based upon an EDD will be able to use Framemaker to compose fully marked-up text and then save that text in to a content management system and eventual use in an online documentation publication.

Something the text does not cover but is becoming increasingly common in user analysis is the creation of taxonomies. Taxonomies are systems of subject classification. These are important to online technical communicators because of the emergence of the Darwin Information Typing Architecture (DITA). DITA provides a framework for storing text elements (for inclusion in online compound documentation) based on subject headings. The key is that DITA does not define the classification of the logical structure of your subjects (taxonomies) for you. That is left for the development/writing teams to accomplish. Once taxonomies are defined they can be hard-coded into the XML data repository for a single sourcing content management system. At this point the authors using the system will be able to construct and manage online content based on custom subject tree structures (taxonomies) for their organization.

Guidelines for Developing Instructions ch. 5 (Ahles/Hennis)

2007-02-24T03:40:00.000-08:00

In this chapter, Inaba, Parsons, and Smillie talk about the use of graphics in instructions. According to them, the role of graphics is to show where the equipment item of interest for each step is located, and what it looks like (39). Graphics are meant to make procedural documents usable and act as a compliment to the text. The graphics should work in a way so that the text can be direct and easy to understand. The chapter then goes into some ground rules on what to use with graphics.

Locators
Locators are the arrows and labels used to identify the items in a graphic. The authors give several rules on how to use locators in a graphic:
Use a locator to help the user find the area containing the item if it isn’t immediately obvious from a general view.
Use a locator and detailed view to show a detail difficult to see on the bigger view.
Use a caption to identify the locator or item unless the identity is obvious.

Detailed View
The detailed views are those that show all the components and parts mentioned in the text of the instructions. Rules given for the detailed view included only use a minimal number of illustrations to support the text, avoid unnecessary details or graphics, and show hands or tools in order to simplify the instruction text.

Types of Graphics
There are many types of graphics that can be used in procedural documents. All of which have their own rules and ways to be used. One of the most common is the line art graphic, which can be represented in two-dimensional, three-dimensional, or traced drawings. Although it is common to think that a photograph is better than a drawing, but a drawing can have much less clutter than a photograph and provide a more accurate representation. The rules for these drawings are as follows:
Three-dimensional drawings should be used for detailed views whenever possible.
Two-dimensional drawings should be used when 3D graphics aren’t available.
Only use traced drawings when 3D drawings aren’t economically available.

Captions and Callouts
Captions and callouts are two ways of supporting whatever type of graphic that you choose to use in a procedure. A caption can be used as a title to identify a graphic or portion of a graphic. The rule given for captions is to use them when the view or location of an item is not readily apparent

Callouts are numbers accompanying an arrow that points to a component or part in the graphic that’s also referenced in the text. For callouts, it is recommended to only use straight lines, restrict their length to one quadrant, place callout numbers at the tail end of each arrow, and arrange callouts in an easily recognizable sequence.

Ch.5 - Rockley, Managing Enterprise Content (Erik Sorenson & Emma Baumann)

2007-02-23T17:12:00.000-08:00

This chapter talks about the content lifecycle. No doubt, as documents circulate many people will have their hands on them. Rockley states that it’s imperative that there be a unified strategy when managing content so that it can be utilized effectively by all who are involved. Rockley talks about the importance of eliminating anything that will impede the development of a unified strategy. The process of implementing a new system and methodology is a costly and time consuming task. Rockley states that it is important to take the time and analyze processes, whether they have worked well or not, in order to determine which ones will make the cut. It can be uncomfortable for those involved to have their work put under a microscope but in the end it will save time and money to identify problems and solutions in the beginning. Below is a look in to the lifecycle.

Content life cycle (in no particular order):
Deliver-Create-Review-Manage

How content is created:
Planning- Identifying need for the content
Design- Physical and contextual content, identifying templates and structure
Authoring and revision- typically all content is reviewed before publication

How content is managed:
Version Control- each document that is saved is versioned along with other documents
Access Control- allowing specific individuals to manage and change content

How content is delivered:
Companies can deliver and often will to multiple platforms. It is important to note who is receiving the content and how it is being delivered (Web, paper, PDF). How is the content managed differently for each medium?

Once all of the aspects of the life cycle are noted, it is important to look at who the content is being delivered to and how it’s being delivered to them. You need to identify the role of each user and basically interview them to see what is effective and what isn’t in their opinions. Taking in to account many views may help to deliver a more objective and useful product. There can be many issues once content is created that otherwise would go unnoticed until production if the interview process is skipped. Rockley states that this process is critical to understand how the intended audience is functioning with the product. There are a myriad of problems that can arise upon further interviewing. These problems can arise from the users and all the way back to the authors. The intention is that everything from the software and the final publication of the product be consistent in order to achieve maximum output with optimum consistency. Rockley includes multiple questions that one can ask each division of the content life cycle in order to ensure that nothing is being skipped or overlooked. Again, most of her questions aim at the goal of creating a unified content strategy, one which everyone is familiar and comfortable with.

Chapter 4 - Managing Enterprise Content-Rockley

2007-02-19T06:43:00.000-08:00

Rockley addresses the need for understanding your organization's needs and goals in order to build an effective unified content strategy. To do this one must look within the organization to find out what type of content management and authoring issues may be present.

By addressing dangers such as economy, missing the market window and legal liabilities an organization can prepare for such situations before they arise. For example, a unifed content strategy can aleviate costs for content development and maintenance. This can free up an organization's budget when times aren't so good.

Rockley also states that within the dangers are opportunities such as faster time to market, new/improved product or service and improved customer support. By having a unified content strategy, it allows information to be changed quickly for new services or products without having to start from scratch. When a company realizes their strengths, they also will see opportunities. Rockley says that by focusing on an organization's strengths, they develop a positive outlook for moving forward. Some of the most common strengths are people, market recognition/ customer loyalty and innovation. A unified content strategy can assist in supporting these strengths for an organization. A good example of this is when customers respond favorably to more effective content therefore becoming more likely to remain loyal.

Rockley writes of the importance for an organization to also identify their goals, which are based on available opportunities, as well as identfy the challenges before moving forward with changes. The chapter states that one way of determining challenges is to ask key people within the organization what they perceive as challenges that could impact the organization's goals. Some of the most common listed are: time and money, resistance to change and maintaining existing deliverables.

To conclude Rockley says it is important to realize that a unified content strategy will not be a solution for all dangers, indentified within the organization. It's focus is intended to help solve problems experienced within the organization in the areas of content creation, management, delivery and communication with internal and external customers. This is just one piece of an organization's overall corporate strategy to addressing dangers, realizing opportunities and building on strengths.

Rebecca Guadagnoli and Jaya Narayana

Guidelines for Developing Instructions: Chapter 4 (Case/Pass)

2007-02-18T22:02:00.000-08:00

Chapter four of Guidelines for Developing Instructions develops a series of rules for task preparation. The authors argue that once the user begins a task, the user should be able to continue to completion without having to stop to find tools, buy supplies, prepare equipment, or readjust materials. Therefore, it is essential to provide the user with a planning information page to explain what a user will need to have or need to do in order to successfully complete the given task. Below are the thirteen rules of task preparation as discussed in the book, many of them directly quoted:

Rule 1. Include planning information at the beginning of the procedure when the task requires any of the following:
- Tools, equipment, or supplies
- Preconditions to be met before the work can begin
- consideration of a variety of equipment configurations
- Different numbers and types of workers
- A number of tasks grouped into different series
When deciding how much planning information to include, consider the expected mode of use, and what the expected user will know, not know, or need to know. Be as specific as possible.

Rule 2. The format for planning information should abide by all of the following:
- it should be consistent throughout the entire document
- it should enable quick and accurate scanning
- it should follow the normal document presentation principles discussed in chapter three.

Rule 3. Use separate instructions for each model unless they are identical or almost identical. This includes multilingual instructions; a set of instructions should include no more than two languages to prevent the user from being lost in unusable information.

Rule 4. When the instructions apply to only specific models of a product, list the models under the heading. The same rule applies to when a step or a task only applies to specific models of a product.

Rule 5. When the instructions apply only to specific equipment items of a product, list the equipment under the heading. This rule also applies to when a step or task only applies to specific equipment items.

Rule 6. Include in the planning information the conditions or requirements that must be met before starting the procedure. Warn the user beforehand (assuming the user will read the instructions first) of whatever needs to be done before trying to do the task.

Rule 7. When there are multiple prerequisite conditions, present the conditions in list form. This will help the user take a step-by-step approach to completing the prerequisites, and will increase the odds that the user won’t miss a prerequisite.

Rule 8. Use ANSI Z535.4-1991 or -1998 Product Safety Signs and Labels as a standard for presenting safety information. These are standards regarding the efficient usage and visual appearance of the words Danger, Warning, and Caution in documentation.
- Danger indicates an imminently hazardous situation that, if not avoided, could result in serious injury or death. Danger should appear in white letters on a red background.
- Warning indicates a potentially hazardous situation that, if not avoided, could result in serious injury or death. Warnings should appear in black letters on an orange background.
- Caution indicates a potentially hazardous situation that, if not avoided, could result in minor or moderate injury. Cautions should appear in black letters on a yellow background.

Rule 9. When safety is a concern, explain the hazardous conditions to the user ahead of time in the planning page. Tell the user what to watch out for, and how to know if they have done something potentially dangerous.

Rule 10. Identify any help required of another person to successfully complete the task. If the user will need other people to be involved in the task, the user should know about it ahead of time so he/she can arrange to get the help.

Rule 11. Identify the resources and materials needed to complete the task. When writing for a technician, you do not need to include things that are always present in the technician’s workspace, such as a set of standard tools. However, when writing instructions for consumers, you should list all tools, expendable resources (gas, grease, tape, etc), or products needed.

Rule 12. When a sequence of tasks is involved, list the items and resources needed by task so the user knows which items are for which task. That way, if the user is only going to complete one task, he/she can prepare just for that one task.

Rule 13. When the package or procedure includes more than one task, provide a table of contents as part of the planning information to help the user quickly find the task of interest.

2007-02-17T20:00:00.000-08:00

Writing Software Documentation
Bynum/Peterson
Chapter 4 – Writing to Support – Reference

Where Chapter 3 addressed writing process documentation (Writing to Guide), Chapter 4 focuses on writing reference documentation. It’s Barker’s assertion that reference manuals are geared toward users who are adept at using the software and only need to go to the reference material for answers in complicated situations. He says that reference documents usually contain very little “how to” to information. Their function is to direct the user over a hurdle and allow him/her to continue on with a task.

Reference (or support) documentation can take many different forms, including:

Command descriptions
Menu overviews
Lists of definitions
Function descriptions
Examples
Error messages

Barker promotes the use of the following five guidelines to develop effective reference materials:

Choose the Right Form of Reference
Barker states that advanced users who go to reference materials are usually looking for a quick answer to a specific question or problem. There are several standard formats that lend themselves to different scenarios—appendices, readme files, job aids, and flipcards. These conventions allow an experienced software user to know where to expect to find the information they need.
Decide What to Include
When writing reference documentation a person must decide which topics to include, such as commands, interface elements, and/or definitions of terms.
Establish a Pattern
“Recognition through regularity” describes this guideline. A successful reference document repeats consistent patterns that provide familiarity to users.
Organize Reference Section
Support documentation requires making decisions on the order of material will be presented. There are two basic organizational options: alphabetical and menu-by-menu. Barker says that there is an advantage to using the menu-by-menu format.
Show How to Use the Reference Section
If users are familiar with the different format support documentation can take, instructions are usually not needed. However, if multiple formats are combined, an introductory section could be beneficial.

2007-02-11T17:01:00.000-08:00

Managing Enterprise Content
Willis/Bach
Chapter 3 – Assessing Return on Investment for a Unified Content Strategy.
This chapter primarily consisted of the setting and meeting of goals when deciding whether or not to implement a unified content strategy. It was divided primarily into three parts, "Identifying goals," "Qualifying goals," and "Quantifying goals." The first two are easily summarized, with statements such as the following:
A fictitious company was used in demonstrating the process of deciding whether or not to implement a unified content strategy. The process was as follows:
Identifying Goals:
- Shorten time-to-market (how long it takes to get an item from conception to sales).
- Reduce cost of content development.
- Improve accuracy and quality of content.
- Reduce manufacturing defects.
These are all noble goals, but they aren't very specific. Without further guidelines, slight improvement can be viewed as successfully completing a goal. Hence, the next category:
Qualifying Goals:
- Reduce time-to-market by two months
- Reduce cost of content development by 25%
- Ensure content accuracy at all times (100% accuracy)
- Reduce defects to less than .01%
The last task of Quantifying the content is a bit more difficult. This essentially breaks down to how much benefit (read: money) the company gains by following these guidelines. For instance, maintaining constant 100% content accuracy can be fairly costly; however, if the company is sued due to a flaw in a manual, the loss could be catastrophic. Even if the company wins the case, the costs for simply defending themselves alone will be far greater than the cost spent on making sure they aren't sued in the first place.
The above process is not possible without gathering metrics (real costs). To do this the following steps need to be taken.
-Identify tasks.
-Measure the duration of a task.
-Calculate the cost of a task.
Ongoing metrics need to be performed as well.
Compare savings and/or value to the cost of achieving a goal.
After calculating the return on investment, the determination to implement a unified content strategy should reveal itself.

Ch. 3 - Guidelines for Developing Instructions (Emma Baumann & Erik Sorenson)

2007-02-10T12:46:00.000-08:00

Chapter 3 of Guidelines for Developing Instructions discusses general presentation principles of creating instructions. All of the principles in this chapter have to do with helping the user acquire information quickly and accurately. They are short-term memory, consistency and fixed syntax, text-graphic, figure-ground ratio, sequence, and multilingual.

The main principle that is explained in this chapter is short-term memory. For developing instructions, the duration of short-term memory should be considered 1 to 30 seconds, and the capacity is four related actions. This means that it should take a user no longer than 30 seconds to read the instruction for a particular step, look at the equipment pertaining to the step, and start the action process. This section goes on to explain this principle by giving specific examples of what/what not to do when writing instructions. The authors advise writers to aim to make instructions usable enough that the user will follow the instructions rather than trying to “wing it” and do it on their own. What is meant by this is that lengthier instructions don’t necessarily mean more usable instructions. Many people skip over long paragraphs, so it’s better to create short, concise step-by-step instructions so that the user will actually read each step.

The consistency and fixed syntax principle is simply based on the idea that using repeated action verbs, sentence structure, and graphics helps the user access and understand the instruction quickly. The text-graphic principle is the idea that text is appropriate for what to do, how to do it, and the sequence to do it in. Graphics, on the other hand, are best suited for the location and object of the action (showing where to perform the action).

Figure-to-ground ratio refers to the item of interest (“figure”) as compared to the area around the figure (“ground”). The text states that a ratio of 1:7 is the max for scanning accuracy and time. Basically, in an illustration, each piece of the equipment is the figure when the user is looking specifically for that piece, and all other parts of the equipment are the ground. In the same way, if callout numbers are used to point to each part of the equipment, then the number a user is looking for is the figure and all other numbers are the ground. This means that if a writer is using callout numbers, they should only use up to seven, unless the numbers are arranged in a structured and recognizable way.

Sequence simply means that a writer should arrange steps in the order that actions should occur, instead of random steps. The principle of multilingual format explains that when creating instructions in two different languages, they should be kept in separate sections so that the flow of information isn’t interrupted.

(Late) Chapter 2 Summary

2007-02-10T07:31:00.000-08:00

Rebecca Guadagnoli and Jaya Narayana

Chapter two of Inaba, Parsons and Smillie discusses the 3 factors that greatly influence the ground rules for writing usable and useful instructions. They are the expected mode of use for the instructions, the basic units of instruction and the different components of information. The chapter walks us through the difference between actions, steps and tasks and how they are written affects the success or failure of the individual using those instructions. The chapter discusses that the expected mode of use for the novice verses the experienced user is quite different. For example the inexperienced user will follow the step-by-step instructions in the beginning and then less after the first couple of times, whereas the experienced user will tend to use the instructions only if they cannot figure out what to do based on their knowledge and experience with the product. When coming across unfamiliar information, both the inexperienced and experienced need the following information: what and when to perform the actions, the order of the actions, where the action is to take place and what the object of the actions looks like. The breakdown of actions, steps and tasks was interesting. The importance was stressed on the use of consistent actions verbs throughout the documentation so as not to confuse the user. Remembering when to go into more detail is key as you can say "remove the faceplate" but when talking about something more complex such as a car engine, you can't simply state "remove the engine" as there are many detailed actions and steps required for the engine to be removed. The authors mention that extensive cross-referencing can confuse the user. It is important that the step-by-step instructions convey what has to be done, how it must be accomplished as well as where, when, order and identity so the user can find it. There are other types of information needed to support instructions such as information to plan the work and description information which assists the user in understanding the equipment or system well enough to make diagnostic decisions. Finally, there is a need for flexibility in writing instructions. This is key in developing simple and effective instructions. Generally the instructions are written to meet the needs of the user, but some of the needs are individualistic.

Ahles/Hennis-Barker Chapter 3

2007-02-09T17:23:00.000-08:00

Chapter 3—Writing Software Documentation

Chapter Layout
Barker writes about procedures in chapter three. The procedures he refers to are called guidance, how-to, and step-by-step. He presents different methods for writing different types of procedural instructions and suggests that learners want to know both how and why the software works.

What is a Procedure?
Barker says there are three types of documentation: guidance level, teaching level, and support level. Teaching level documentation is also called tutorial; the object is to teach the user the program and its uses. Support level (or reference) is user-defined; the user determines where they find the information and how much of that information they will use. Guidance level documentation falls somewhere in between teaching and reference; the user may be familiar with the program and only needs a reminder of what to do.

Guidelines for Procedures
According to Barker, authors need to make the procedures useful by tailoring them to activities that normally occur in the workplace. The procedure will be much more meaningful to the learner if it relates to something he/she does in the workplace every day. The procedure should be recognized as a building block that fits into the larger picture of what the office accomplishes in a normal day.
The writer needs to determine what the end-user will need to accomplish their task. He does this by doing a user analysis (to be covered later). The user analysis will determine how much or how little information will be included in the procedure. Barker (p.68) says that the writer will use a combination of tools in the procedure including:

Screen Shots
Cautions and Warnings
Tips for Efficient Use
Tables w/ Option for the User
References to Other Resources
Explanations

Formats

Barker suggests that there are basically four formats to use when writing procedures. He calls them the standard format, prose format, parallel format, and embedded help. All procedures, regardless of type, need to have evaluations done on them to makes certain that they are reasonably complete and accurate.
The standard format contains the steps in a numbered sequence from first to last. This type of procedure is often seen in instruction manuals such as software books. Most of us have seen it before, and Barker suggests that user recognition makes this type of procedure useful.
The prose format puts the procedure into sentences and paragraphs instead of numbered steps. This type of procedure is used for simple tasks done on a simple interface.
Parallel format is used with complicated fields or boxes. Numbered (lettered) steps are used along with prose explanations.
Embedded help is used when the user needs help that is specific to his location within a program. Embedded help uses markers within the program which, when called upon, present the user with information that is relevant to their place in the program. Embedded help uses various methods for presenting information including tips, cues, demonstrations, and trouble-shooting.

Barker ch 2 Pass/Case

2007-02-03T19:22:00.000-08:00

Chapter 2 of Writing Software Documentation covers an overview to writing tutorials for computer programs.
Barker begins by identifying seven guidelines essential to writing an effective tutorial:
Identify User Actions You Need to Support—in other words, analyze your user and what specific tasks they will be doing with the program. Tie the program’s features back to the user’s goals and how they can use the program to accomplish them.
State objectives as Real-World Performance—Be realistic. Start writing a tutorial by stating, in measurable terms, what tasks you want the user to be able to do after using the tutorial. Often it is beneficial to state these goals in the tutorial for the user to see.
Chose the Right Type of Tutorial—Analyze your user and decide what format of tutorial will suit their needs the best. 5 types of tutorials Barker discusses in the text are: The guided tour, the demonstration, the quick start, the guided exploration, and the instruction manual.
Present Skills in Logical, Cumulative Structure—Imagine the typical-use scenario for your user, and use it to build your tutorial structure. Order your tutorial steps, tasks, or modules based on how your user will most likely be using the program once they learn how to use it.
Offer Highly Specific Instructions—Be as specific as possible. Don’t give general or vague information (such as telling your user to ‘enter any name’) just because your users have different perspectives of various things. Guide the user to exactly where they need to go, and tell them exactly what will help them get there.
Give Practice and Feedback at Each Skill Level—Be positive and encouraging towards your user, and remind them of the benefits of learning how to use the program.
Test Your Tutorial—Be an advocate your user by making sure that the product they get will do what they want it to do.
The second half of this chapter is dedicated to the difference between elaborative and minimalist approaches when writing tutorials. These two perspectives on writing seem to be dichotomic, one valuing thoroughness and the other valuing brevity. Sometimes the minimalist approach will be a more useful approach for a project, and sometimes the elaborative approach will be more useful, so it is worth it to explore both perspectives.
The elaborative approach focuses on peoples’ ability to retain information more thoroughly through repetition. To achieve this repetition, the tutorial utilizes introductions, summaries, examples, skill tests and a variety of other ways to present information. This approach is better suited for users that are new to computer usage, complicated procedures, or for situations in which the user must learn abstract concepts.
In contrast, the minimalist approach plays off the belief that users do not want to read instructions or unnecessary information. To follow these beliefs they try to teach using specific tasks related to the use of the software while letting the student explore the program. This approach is better suited for users that are familiar with computers, programs that require creativity from the user, or programs that have intuitively-designed interfaces.

Rockley, Chapter 2 Summary - (Haupt)

2007-01-31T07:40:00.000-08:00

This chapter focuses on one of my favorite topics in the world of documentation technologies - element reuse.

This capability first become possible when Dr. Charles Goldfarb, an IBM researcher, invented Generalized Markup Language (GML) during the 1970s. Later morphed into a more advanced implementation of structured document markup as Standard Generalized Markup Language, this invention became one of the foundational technologies upon which the World Wide Web was built. Most people do not realize the HTML is merely a simplistic Document Type Definition (DTD) of SGML. An SGML document comprises of three parts, the Declaration (for example it can specify "Transitional" HTML, the Instance, and the DTD. In the World Wide Web the DTD is never transmitted. It is retained within the browser's code itself.

For the purposes of "reuse" we focus on the DTD. The DTD is a way to describe the logical hierarchy of a document. The logical structure of a document is separated from the typographical formatting of the document (formatting is contained in a Formatting Output Specification Instance - a FOSI). When the World Wide Web was invented SGML was found to be incompatible with it unless a browser plugin was used. Therefore, among other reasons, XML was created - a simplified and web-compatible version of SGML.

XML can be used with either a formal DTD (Yes, you can code your own XML DTDs!) or a valid schema. Either approach defines logical structure of a class of documents. In the world of technical communications XML data repositories are used that contain multiple DTDs/schemas. Authors don't write documents. They write elements. An element is simply an instance of a subset of a structured document defined by the DTD. The document elements are stored within the database and are available through a front-end editor such as Arbortext. Technical Writers are able to browse a library of elements and select the ones they wish to incorporate into their document. In the event that they can't find a suitable existing element they have the option to create a new element and write the content for it.

An XML-based content management system keeps track of the element reuse, version control, audit trails, records management, security, etc. and collects the elements at publishing time. Users can specify a wide variety of output formats including HTML, TROFF, RTP, PDF, and Java Help, etc.

Additionally, publishing outputs can be customized for individual readers - pulling a subset of reusable elements from the repository for each type of need - for example an "installation" view, a "training" view, or a "maintenance" view.

Rockley correctly identifies the benefits of an element reuse strategy: 1) Increased Consistency, 2) Reduced Development and Maintenance Costs, 3) Rapid Reconfiguration, and 4) Translation.

The concept of reuse has existed for a long time but is only recently gaining large-scale traction within industry. Software developers have long used reuse of code. A Class Library is simply a collection of previously used code that a developer can reuse for new applications under development. Technical Communicators are now seeing a plethora of solutions available to meet their element reuse needs. Rockley refers to element reuse as "single sourcing". Personally, I've never heard that term before in this context. This is probably because I have approached the problem from an engineering viewpoint instead of from the technical writer's viewpoint - hence I learned the jargon of documentation engineering and have used those terms to describe the environment Rockley describes.

Rockley correctly points out that reuse is not appropriate for every document. I am currently working with Astoria Software to implement a reuse solution within Wells Fargo. Astoria provides a three-pronged test to determine if a document is suitable for reuse: 1) document must be dynamic - constantly being updated, 2) document volume must be large to meet economies of scale, 3) document production processes need to be streamlined.

In conclusion, employing element reuse solutions represent an accelerating trend in technical communications. Learn to love it!

Inaba, Parsons & Smillie, Chapter 2 Summary - (Haupt)

2007-01-31T07:13:00.000-08:00

This is an excellent introduction to procedure writing. For my own definition I've always thought of a procedure as a set of steps that a person performs to achieve a specified outcome. I consider a "process" to be a set of related procedures. Inaba, Parsons & Smillie offer us a similar definition - "procedures as instructions that lead the user step by step through a number of tasks until the work is completed".

I agree with the principles of procedure writing taught by Inaba, Parsons & Smillie but I feel they do not delve deeply enough into the analysis of information types. If any of you ever have the opportunity, take a class from Information Mapping, Inc. (www.infomap.com) called "Developing Policies, Procedures, and Documentation". The theory behind Information Mapping is that all information can be categorized into six different Information Types. One of these types is an action type called a "Procedure." Once an author identifies that he is dealing with a Procedure, he can utilize various Information Mapping techniques to write the procedure. The most common technique is a Step-Action table. In other words, you create a table with all the steps numbered. Then in each row you enter the specific action a user takes for that step. I can't teach the entire method here as that would violate Information Mapping's copyright - but I highly recommend the user of Information Mapping in real-world projects. The Information Mapping methodology can be used within Microsoft Word as a plugin called Formatting Solutions. A second plugin, called Content Mapper, allows technical writers to use the Information Mapping methodology in a structured documentation environment, i.e., an XML data repository.

Inaba, Parsons & Smillie wrote this as a very short chapter - but they made a number of good points in these few pages: 1) Procedures contain steps and step represent user actions, 2) be aware of the need of "packaging" information into large organizational units such as chapters, 3) be aware of the perils of cross-referencing, 4) multiple models require multiple sets of procedures, 5) integrate text with graphics, 6) plan the project prior to writing the documentation, and 7) be flexible - requirements vary.

Barker, Chapter 2 Summary (Haupt)

2007-01-31T06:44:00.000-08:00

This chapter, on tutorial design, is an excellent resource for both new and experienced technical writers on the art of instructional design techniques. I especially liked the emphasis on user actions as it relates to writing procedures.

As my career has not been focused on writing tutorials for end users (rather, a focus on writing documentation for technical professionals in the disciplines of network engineering, operating systems engineering, and software engineering) I am not as well versed in this topic as I should be.

Barker rightly focuses on the essential document design principles for educational and instructional documentation. It is evident that a comprehensive process must be followed in order to produce effective tutorials - both in the planning stage and the production phase of a project. Barker points out a number of user "traits" that writers have to take into account in writing tutorials, including the fact that users like to feel as if they are in charge, that users tend to "jump the gun". users will skip information (just like in a reference manual), and that users will tend to read the tutorial once, at best, and then refer back to it infrequently.

I've gained a greater appreciation for technical writers specializing in instructional design. An impressive skill set is required to create professional tutorials. The very first work I ever did in instructional design was as a high school sophomore in 1971. My father, a professor of mathematics, was co-authoring an Algebra text book with another mathematics professor. They hired me to edit the grammar and type the manuscript. I did the job using an old SCM long-carriage typewriter that had special mathematical symbols added to the key set. While producing the proof for the printer, I was actually forced to look very closely at the way the book had been logically assembled. Looking back 36 years, I can identify techniques the authors used in the book that Barker now clearly identifies for me. These techniques include: 1) Identifying Skills to Teach, 2) Identifying Objectives, 3) Choosing the Right Type of Tutorial, 4), Presenting Skills in a Logical, Cumulative Structure, 5) Specificity of Instructions, 6) Practice and Feedback, 7) Testing, 8) Elaborative Tutorials, and 9) Minimalist Tutorials.

This chapter is a great resource that I will refer to in the future if I am called upon to create tutorials.

Chapter Summaries

2007-01-28T19:39:00.000-08:00

Managing Enterprise Content: Chapter 1

Chapter one discusses the large volumes of content that organizations put to support their products, services and business processes. It is important to get the content out to the right people at the right time as well as in a format that is understandable to your audience. While concentrating on the format a writer must always think of who is going to be reading it and what are they going to use it for.

The content comes from many different departments within an organization. It comes in forms such as newsletters, brochures, training material, press releases, speeches, product information, etc. These materials are published through various media and require different formats. It is important for an organization not to get trapped in a content silo where none of the departments interact with each other on content being put out therefore creating a cycle of creating and recreating. Many times the information is changed during each recreation. Lack of awareness of others working on the same content, shortage of time and inconsistent amounts of information are leading contributors which create these content silos. The effects of content silos can result in increased costs, reduced quality and possibly ineffective materials. Some of the effects of content silo are as follows:

poor communication
lack of sharing
reduced awareness
lack of standardization and consistency, higher cost of content
creation, management and delivery
content users suffer

One solution is to establish a unified content strategy. A unified content strategy is a repeatable method which helps in identifying all content requirements at the beginning, creating consistently structured content for reuse, managing the content in one location and putting it all together on demand to meet the customers' needs. It all begins by analyzing your audience, their information needs, processes and technology. You need to think about who needs and uses what information, how the users are currently supported by the information and how to produce the information. You have to realize what information is can be reused across information products and what elements are unique to a particular information product. Information such as a product description can be considered reusable information. Authors can then share responsibilities for writing core and reusable content. The technology used must be based on the business needs in order to support a unified strategy. By have all content coming from a definitive source you can be sure authors are not wasting time searching for content and the most accurate content is always used. Some of the benefits of unified content are:

faster time to market
better use of resources
reduced costs
improved quality and usability of content
increased opportunity to innovate
improved workplace satisfaction
increased customer satisfaction

To implement a unified content strategy means to think about creating, managing and storing content in new ways. A unified content strategy consists of a content management system, reusable content and unified processes. Content management is not only concerns technology, but is also about the nature of your business and content, people, processes and tools. By having reusable content an author can mix-and-match content to meet the specific information needs. Unified processes is simply ensuring that all departments are aware of what content exists (authors can reuse existing content automatically), all processes are repeatable and transparent no matter which department and which authors are using them. A unified content strategy works everywhere content is used, stored and managed in an organization. The following are some of the areas where content strategy can work in a business:

customer data
web site and e-commerce portal
product support and training materials
policies and procedures
proposals
regulatory reports

In conclusion, a unified content strategy can include content created by a single department, several departments, an organization or an entire enterprise. It can be started in one small area and then expanded into others slowly. The best path to take is whatever works best for your organization.

Comments:

Content silos are a result pressures and structure of an organization.
The content process itself is one that often occurs in isolation which creates many inconsistencies and possibly extra work.
Poor communication can happen when one group fails to inform another group that something has changed.
The lack of sharing amongst authors can result in inconsistencies, mixed messages to the customer and increased costs due to each other recreating a new document every time.
When information that is the same, similar or related exists in multiple places, it can differ in content and message. Users can't always tell which is correct.
Authors can avoid the issue of format by using style sheets to convert the product description to the proper format. This doesn't take away creativity, but instead allows creativity where it has the most value.
A unified content can benefit the company by freeing up time and allowing authors to focus on innovation. This can improve the quality of the content and make your product stand out in the marketplace.
Product support materials can form a continuum that takes you through marketing materials through training, product support, troubleshooting and problem solving.
A company's web site represents key information and unified content strategy ensures the web content is managed effectively.
Companies can benefit by unified content strategy for their large reports. It will ensure that the content is accurate wherever it appears.

Guidelines for Developing Instructions – Chapter 1

This chapter is the introduction to the book. It talks about the purpose of the book which is to provide guidelines to help personnel who may write instructions for products. The instructions can be step-by-step or serve as a reference that only use it when they are in dire need of information. The book will give examples of instructional materials such as: assembly procedures, "how to" manuals, user's manuals, shop manuals, etc. The book does not encourage the use of commonly accepted task analysis. The chapter states that most instructions are procedural and the guidelines can be useful to authors of all documents.

It discusses how there are a wide range of products and there are just as many writers assigned to write the instructions for those same products. Much of the time the quality of the instructions greatly affects the care and use of products by the consumer. A lack of standard for instructions is one of the reasons why many products are not supported by usable instructions. The guidelines throughout the remaining chapters are based on the principles connected to meeting the informational needs of the users.

Helping writers develop procedural material is the primary focus of the book. Step-by-step instructions are needed because these instructions are the main need of users of products. The book contains rules of both underlying principles and specific guidelines based on principles. The reader will be able to customize the guidelines when necessary by referring to the underlying principles.

The remaining portion of the introduction goes into what each chapter will detail. It also discusses that the appendix provides a checklist based on the rules of the various chapters. One can evaluate instructions through this checklist and will be able to determine if revision of usability is necessary as well as provide assistance for writing new instructions.

Comments:

It is recommended that writers learn the principles in Chapter 3 and use them to adjust various guidelines as needed.
Of the presentation principles, the text-graphic format is the most effective application when working with step-by-step instructions.
Chapter 5 covers the ground rules for graphics.
Chapter 6, Language Control, covers the text portion of the format.
Fixed list command verbs are required with the use of the format.
Chapter 6 contains a basic list of 87 command verbs and definitions.
The introduction says that Chapter 8 is a very important chapter as it presents a recommended process for creating instructions and then making sure they are technically correct and usable.
Writers will sometimes work with subject matter experts which results in the responsibility of the instructions to be shared equally.
Chapter 8 also provides a systematic way to develop procedures.
Special modifications can be found in Chapter 9.

Barker, Chapter 1.

This chapter is a good introduction to software documentation and gives many examples of how one is created. It explains the 3 forms of software documentation, and the benefits of each. Depending on how experienced your user is and what the document is meant for will determine which form to choose.

Tutorials-used to teach users basic actions

Procedural-used to guide users through specific tasks

Reference-used to supply information to users about the program

Barker also says that there should be a connection between the old software and the new. This way the user will be able to benefit more from correct usage of this software. The steps he describes for production of a successful software manual are re-visited throughout the book.

Barker talks about Task Orientation, which is very important because it is meant to help the user to be more comfortable with the software in the workplace. Many users simply read through the one task they need to know and then skip the rest, and the user cannot be efficient with the software this way. This is illustrated when Barker explains the difference between a default user and a task-oriented user.

Default user-notion that a user needs to know the program works in order to apply it at their job. This person is thought of as anyone who uses a computer.

Task-oriented user-one whose software use fits with his work environment. This user would make the program more versatile for use in the workplace. Having this user as the targeted audience for your manual makes the user feel more responsible and more challenged, while still having enough information. Knowing the difference between these two and applying it to your writing is the big challenge with creating software documentation.

Managing Enterprise Content - Chapter 1 (Peterson)

2007-01-26T16:33:00.000-08:00

Chapter 1 - Content: The lifeblood of an organization really hit home with me. I almost felt as if the authors had been observing the company I work for.

A content management system was purchased by our IS department to update our corporate internet site. Several months later, it was strongly recommended that the corporate intranet department, which I work in, should convert to that the system too. Two totally separate worlds were about to collide.

On page 10 of the textbook it says, "After careful research, they [customer support area] present their business case to management for the [content management] product they have decided to purchase. However, the web management group has already purchased its system, and is expecting it to be installed any day, so the customer support area is told to use the same system." After reading that, I felt better knowing we weren't alone!

The silo mentality mentioned in the book was alive and well at my company. After several months of struggling to understand one another, IS has decided to support the software my department uses (FrameMaker and WebWorks) and my department has begun building new intranet sites using the content management system and its site styler features.

I wish I'd read this chapter 12 months ago! It spelled out in non-threatening terms exactly what is meant by "content" in organizations and what a content management system intends to do. I have now seen firsthand the advantages a good content management system provides. It really does lead to consistency and time-savings. The system we use, although lacking in some design areas, has proven to be an enhancement to my department's online documentation procedures.

Guess that makes me a convert.

Chapter 1 Summary - Managing Enterprise Content (Haupt)

2007-01-26T09:54:00.000-08:00

Ann Rockley, Pamela Kostur and Steve Manning have identified possibly the largest documentation problem facing major enterprises today - silos of information. They seek to eliminate these silos through a "Unified Content Strategy". The problem is easy to identify and difficult to eliminate.

The typical large corporation has multiple document management systems, each containing specific types of documentation. Furthermore, these disparate systems are rarely compatible with each other, resulting in an inability to integrate them one to another. Compounding the problem is that the companies also employ web-based content management systems - designed to automate the management of internet and intranet-based documentation.

Admittedly, there exist enterprise-wide applications designed to extract knowledge from the entire organization's digital resources. A good example is Autonomy (http://www.autonomy.com/). But such a solution is very expensive and also intrusive. These types of programs can spider an enterprise-wide network, using Bayesian logic to find relationships between seemingly unrelated pieces of documentation. In other words, these programs find the context of the documents.

The authors maintain that the solution to the problem isn't just technological. It can be solved, they argue, by learning and implementing a strict methodological approach to the creation and management of enterprise-wide documentation. As far as technology is concerned, the authors advocate the use of reusable content modules - commonly referred to as "elements" in the world of XML and SGML (Standard Generalized Markup Language). These elements can be reused simultaneously in multiple documents. No longer are documents created as standalone pieces. Rather, reusable elements are combined on demand to create virtual documents.

I look forward to reading the entire book and learning how the authors feel they can manage enterprise-wide content management systems, XML, SGML, DITA, legacy documentation applications, and the people who contribute documentation to them.

Chapter 1 Summary - Writing Software Documentation (Haupt)

2007-01-26T09:31:00.000-08:00

I begin my review of Chapter 1 with a criticism. Too much focus is placed on the writing of software end user documentation. In my career I have found that writing software documentation involves a great deal of documentation that is much more complex. These projects include writing functional requirements, end use cases, trace matrices, documenting source code, and writing application-specific technical reference manuals.

This chapter assumes that the writer will be focusing on end user manuals - assuming a near complete lack of technical expertise among the potential readers of the manual. In fact, the authors state that they are only considering three types of documentation, user manuals, reference manuals, and tutorials. Totally ignored is the massive amount of documentation generated during the software development process - a process in which the involvement of a technical writer is invaluable.

I also take exception to the author's list of "Tools of Software Documentation". He focuses on graphics, grammar, page layout, and document design. While necessary, these elements are hardly complete. I would add proficiency in database administration tools such as SQL Enterprise Manager, coding (Java, C#, .Net, C++, and Visual Studio, etc.), and LAMP (Linux, Apache, MySQL, and PHP). For a technical writer to truly be effective he/she needs to possess true technical abilities in addition to the requisite writing ability.

Finally, one last criticism. The book focuses on page layout. In a world of XML data repositories and compound documents this focus has become irrelevant. Authors now concentrate on the text and not the formatting of the text. Automatic formatting is accomplished on the back end by page rendering engines such as Antenna House or RenderX. The whole point of XML is to separate the physical formatting of a document from the logical structure of the document. Additionally, the purpose of Darwin Information Typing Architecture (DITA) is to separate the structure of the document from the content of the document. The entire industry is moving to a model in which physical formatting is automated and delivered at the moment of publishing - not at the time of document authoring.

Chapter 1 Summary - Guidelines for Developing Instructions (Haupt)

2007-01-26T09:11:00.000-08:00

Chapter 1 serves as an introduction to the book. Noteworthy in this chapter are the revelations that the authors have abandoned the commonly used approach of task analysis in developing instructions, and the widely used methodology of book design. Rather, the book teaches a method focused on human factors engineering.

I find it interesting that the authors have not chosen to address the requirements of ISO 9000 (including Conformance Models 9001, 9002, and 9003) when discussing procedure writing. ISO 9000 is an international standard for process, procedure, and work instruction documentation. It is the business process and procedure element of the Malcolm Baldridge National Quality Award Criteria. Many large and/or international companies adhere to the methodology of ISO 900o in their procedure documentation.

The book stresses the importance of graphics in procedure writing. The book stresses a team approach to be used in writing procedures, including the involvement of graphic artists.

Technical writing commonly involves a team approach. It is customary for technical writers to work with subject matter experts (SMEs) in the development of procedures. It has been my experience that most technical writers are not as proficient technically as they are in the art of writing. This lack of technical knowledge on the part of technical writers creates an environment in which they rely on SMEs for direction in their writing projects. The book explains how to produce documentation with the assistance of various team members including writers, editors, graphic artists, management, and SMEs (typically engineers).

Also receiving special attention is the subject of maintenance documentation. Technical writers usually create procedures in three different phases of a product life cycle including design, training, and maintenance. Typically, these documents are dynamic - constantly being updated as revisions become necessary due to design changes, software upgrades, changing hardware specifications, and training requirements.

Barker Ch. 1 Summary (Erik Sorenson & Emma Baumann)

2007-01-25T23:57:00.000-08:00

This chapter deals with the principles that are applied when a software document is created. It deals with how writers achieve their goals of encouraging users to learn their program and the efficiency with which that program is then used. And on a brighter note, for those of us who are unfamiliar with software documentation, it provides an introduction and many examples.
Barker says that all software documentation should show connections between the new software and how the user will benefit from correct usage of the software in the workplace. He lays out nine steps for production of a successful software manual, which are found on pages 4 – 8. These steps are important to note and become familiar with because they will be a continuing trend throughout the text.

Task Orientation is important because, as we mentioned above, it attempts to integrate the software with the user on a professional level, meaning the user and their workplace. Barker contends that it’s not always easy for a user to be truly efficient when using the software manuals because they may inevitably pick the one thing they need to know and dismiss the rest.

Barker goes on to show just how important task orientation is by describing the characteristics of both a default user and a task-oriented user. Basically the default user is the perceived notion that a user just needs to know how the program works in order to apply it at their job. Barker says that earlier manuals were based on this “default user” (who is thought of as simply ‘a person who operates a computer’), which caused many users to often have the following problems: feeling like less job skills are required of them because of the computer’s ability to perform tasks, feeling isolated in their work, feeling overloaded with information, and so on.

Barker then says that designing a document based on what he calls a “task-oriented” user (one whose software use fits with his work environment) would solve these problems by making the program applicable to different workplace tasks. Keeping the task-oriented user in mind while designing software documentation can make the user feel challenged, self-managing, and supplied with information. Instead of developing negative opinions about new software, the task-oriented user will take a positive approach and learn willingly because of the document design. It is important to note the differences between the default approach and the task-oriented approach in order to better understand what challenges may face a software documentation specialist.

Chapter 1 also briefly discusses the three forms of software documentation, and what each one is used for. Tutorials are used to teach users basic actions, procedural documentation is used to guide users through specific tasks, and reference documentation is used to supply information to users about the program. Choosing which form of documentation to create depends both on the user (novice or advanced) and the purpose of the document (to teach, guide, or supply information).

Michael Nelson

2007-01-22T16:34:00.000-08:00

My first Blog.

Hello

2007-01-22T14:41:00.000-08:00

Hi, my name is Lindsay Case. This semester has started out really crazy for me and I can't wait for it to calm down. I live in Mankato with 2 roomates and a dog. I am originally from Sleepy Eye MN. I have taken a lot of online classes and although they are convienent and much warmer than walking to class, they have their fair share of obstacles too. Hopefully this class will be smooth sailing. I'm very excited to work with all these new programs Lee has lined up and I hope to expand my computer savvy.

Welcome to Jaya

2007-01-16T15:09:00.000-08:00

Hi everyone, my name is Jaya Narayana. I'm originally from Plymouth, Minnesota, but have been living in North Texas since I was 12. I started college there and transfered here because...I missed the cold winters? No, that's not it. I think I just wanted to come back, and I have a lot of family up here as well. This is my first tech comm class and I look forward to minoring in it. Hope everyone had a nice break!

Emma's Intro

2007-01-15T14:27:00.000-08:00

Hi everyone, I'm Emma Baumann. I was born and raised in Mankato. I'm 21 years old and in my fourth year of college - I received my AA degree from Bethany College in 2005 and then transferred to MSU to complete a Bachelor's Degree in Technical Communication. I'm currently going to school full-time and also have a part-time job as a graphic artist/marketing assistant for the student union.

I have taken a few other online courses over the past year, and am still getting used to having class online since every class uses different software and methods. I don't know much about online documentation, so I'm hoping that this course will give me (and everyone else!) some good experience in that area. :)

Diving into 2" of water is bad.

2007-01-14T21:10:00.000-08:00

Karen again, trying to do things the correct way. If the best way to learn is through one's own mistakes then I am going to be very busy and very smart by the end of the semester. I feel a bit overwhelmed right now as this is my first online class. I WILL GET THROUGH THIS!

Old student but young at heart

2007-01-14T20:27:00.000-08:00

Greetings All,

I've been out of college for so long that if you cut me in half you could count the rings! I've spent over 25 years working in the technical writing profession in one form or another and I've finally decided to earn a M.A. So here I am.

I spend my days buried several floors underground in a sub-basement in downtown Minneapolis. I work for Wells Fargo Bank as a Business Systems Consultant in the Server Software Engineering Department. My office is in a high-security area of the bank's Northern Operations Center. I'm in a facility that houses one of the bank's data centers so I have to go past armed guards, security cameras, and man-traps to get to work each morning. But once I get past the security measures I enjoy the rest of my day.

I look forward to getting to know each of you. Technical writing is exciting to me and this class will be a wonderful experience to learn new techniques. This old dog is going to learn some new tricks thanks to Dr. Tesdell and each of you!

Carl Haupt

An Introduction

2007-01-14T07:17:00.000-08:00

The format of this blog seems to be an introduction followed by a brief bio, so here we go. My name is Larry Hennis. People keep asking me what I want to do when I grow up, but I haven't decided yet. I am old enough to join AARP, but I am still 21 years old (in my own mind, anyway). My interests are many and varied, and a look at my college experience shows that.

I have an undergraduate degree in Business Administration with concentrations in Management and Human Resource Management and a minor in Accounting. I am (finally) in the latter stages of completing a master's degree in English with a Technical Communication focus. I also spent a year in law school, but that turned out to be a disaster (horrendous outside distractions that sank me-another story for another time).

I have taken other online courses, and this one looks like it will be challenging and interesting. I look forward to working with everyone and I want to wish everyone good luck in this course!

A few minutes with Wes

2007-01-13T17:31:00.000-08:00

My name is Wes Ahles (last name is pronounced ah-les) some of you may recognize me from other online classes. I started my collegiate expereince by earning an Associate in Arts degree from Riverland Community College, followed by a Bachelor of Science in English at MSU. This class will finish out my second year at graduate school. I live in Hartland, a very small town about 40 miles south of Mankato, and work a Friday-Sunday full-time job in Waseca. I haven't had much experience in online documentation so I'm interested to see where the semester will go.

Hello from Anne

2007-01-13T16:45:00.000-08:00

Hello, everyone. My name is Anne Peterson--although I have an alter ego named Sabina Peterson who shows up on offical class records. You can call me either Anne or Sabina (long i). I answer to both. This is my 4th online class for the Technical Communications Certificate program.

I live in Owatonna and work at Federated Insurance Companies in the "Corporate Documentation Services" Department. That means I help authors write documentation for our intranet. Our department is only one year old and the courses at Mankato have been invaluable.

I see some familiar names on the class list and look forward to working with you all this semester.

Welcome to the Engl476576 blog

2007-01-13T10:25:00.000-08:00

We are the instructor and students of English 476/576, Online Documentation, a course offered in the technical communication program at Minnesota State University, Mankato. We will discuss the readings in our textbooks here on the Engl476576 blog.