Barker chapter 14: Designing Indexes

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

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.

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

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

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

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?

1. 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.
2. Determine a place for the workflow to end.
3. Identify all the players from the beginning to the end of the workflow. A task should be associated with a role.
4. Sketch the tasks by identifying which tasks align with each player. Look for potential conflicts.
5. Identify interactions patterns among players and tasks.
6. Set timeframes for tasks and select an start and end for the entire workflow
7. Identify notification patterns.
8. Identify approval patterns.
9. Determine the "what if" scenarios that may affect the workflow.
10. Examine final workflow for simplification.
11. 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

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)

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

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

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.