Central Works: Writing and Database Technology

WRITING AND DATABASE TECHNOLOGY

NOTE: Article originally written in 1996

Data reports refers only to printed reports that are composed of both tables of numbers, words, or both. Tabular reports are the most common.

Reports consisting of data tables are vital to almost every business function. These reports are used by marketing, budgeting, production, and sales. This means many people may require many different versions of the same report, catered to their own personal needs. These reports can be intended strictly for the specific person reading them, or for a general group of readers.

The value of reports is organized record keeping and problem solving. However, many businesspersons lack the proficiency to generate a form and content that directly address a pressing business problem. According to a survey, managers were spending almost half of their work year looking for such data. Often, current reports would need to be adjusted and mathematically figured so that the new reports actually did provide the correct data. This process can be very frustrating and little attention is given in either business or in technical and professional writing classes to building people’s skills in writing effective data reports.

To develop these reports, writers have to transform raw data (“facts”) into meaningful information for a given context, audience, and organizational purpose, and it must be communicated in an effective way. This transformation is a rhetorical activity. People learn about data reporting, not through specialized courses, but in computer training classes, therefore stressing technological skills over rhetorical. This sends the message that knowing how to operate a technology is commensurate with knowing how to use it to its full advantage to achieve a purposeful exchange of information.

Data reporting demands a dynamic interplay between a writer’s rhetorical and technological skills. As such, it should have a place in technical and professional writing classes. The purpose of this essay is to explore unique skills and knowledge that data-report writers need to learn in order to produce effective data reports. Mirel argues that if data reports are to serve readers’ needs for record keeping and problem solving then writers’ technological skills must serve their rhetorical aims and strategies.

DATA REPORTING AS COMMUNICATION

To analyze the interactive rhetorical and technological competencies involved in data-report writing, Mirel first presents a framework for understanding the communicative dimensions of report writing. Historically, data tables have been associated with scientific rationality. However, this asocial view of tabular data ignores the inescapable rhetorical intentions and practical consequences of retrieving and reporting data. Many researchers argue that facts are not simply transferred from senders to receivers, but rather that it is based on a relationship between readers and writers. This relationship-based view of constructing knowledge casts a new light on the writing of data reports.

Many composition specialists examine computer literacy and electronically produced information through this constructivist lens. However, they omit databases and nonlinear tabular communications from the technologies they examine, such as word processing, desktop publishing, electronic conferencing, and E-mail. Some research in rhetoric, visual design, and human factors, however, does focus on database-related communications. This research reveals that

• Key rhetorical strategies inform data searches, retrievals, and reporting;

• Rhetorical and technological skills mutually support and shape each other; and

• Designs for functionally effective tables must facilitate readers’ strategies for answering business questions.

Key Rhetorical Strategies Inform the Searching for, Retrieval of, and Reporting of Electronic Data

Sullivan (1986) concludes that rhetorical invention is the defining feature of electronic data searches. She finds that searchers must possess the following skills, all of which involve invention processes:

• Knowing the meaning of “invisible” data that are stored in the system;

• Focusing on what is at issue in a communication situation (stasis); and

• Determining the most effective topical orientation of a particular purpose (topoi).

Rhetorical invention also comes into play in reporting data. Research finds that writers do not experiment with enough formats. Therefore, they rarely produce the best format for their exact purposes. As on overview of qualities necessary for effective data reports, Zmud (1978) identifies four characteristics that are implicitly rhetorical, as noted in the parenthesis:

• Quality of information (selecting appropriate and relative data);

• Accuracy and sufficiency of information (selecting the right scope and detail);

• Quality of format (sequencing, ordering, and chunking information effectively); and

• Quality of meaning (evoking emphasis, patterns, and relations through logic and layout).

Skills in Rhetoric and Database Technologies Support and Shape Each Other

A number of studies show an inextricable link between rhetorical and technological strategies in data searching and retrieval. Researchers find that unless people know (or invent) (a) the meaning of the data, (b) the significance of data relationships, and (c) the right level of detail for a questions, they will have difficulty understanding the basic program logic of search principles and data structures.

Designs for Functionally Effective Tables Must Facilitate Readers’ Strategies

Developing effective tabular displays of data should lead writers to research on visual rhetoric. A list of such research reports is found on page 384. These researchers emphasize the need to design tables to answer questions that readers will ask. There are three distinct levels of questions and answers: elementary, intermediate, and overall. The goal for designers is to choose a tabular image that answers the majority of questions the information is capable of generating.

Functionality is also important in designing tables. While simplicity works best as an aesthetic preference, it is not always the best strategy for displaying information. Designers should realize that the effectiveness of a table does not depend on how much information it includes, but on how information is layered and ordered to facilitate readers’ interpretations. Developing effective data reports requires writers to be adept at rhetorical strategies for invention, arrangement and delivery, and to understand the logic and capabilities that a program offers for defining, searching for, and retrieving data and for organizing it into printed reports.

METHODOLOGY

To study the rhetorical and technological skills involved in data reporting, Mirel analyzed readers’ reported responses to the actual data reports that they receive and use at work. From these responses, she inferred some knowledge and skills that writers should have to develop effective reports.

Mirel had 25 respondents – project administrators in a national research laboratory. She gathered information on their responses to a report that they received each month. The report was generated from a mainframe financial system. The respondents used the report for tracking costs, managing accounts, and assessing budget over- and under-runs. Mirel conducted a semi-structured interview with the respondents that usually lasted an hour. She asked the respondents the same four questions; then she analyzed the participants’ combined responses for patterns in their strategies and purposes for analyzing the report, for their satisfactions and dissatisfactions with the report, and for their methods of overcoming problems with it.

Mirel showed that the respondents are uniformly dissatisfied with the report and use the report for the same general purposes.

RESULTS

Each month, respondents use the report to answer four central cost-accounting questions: (1) Are all the changes legitimate? (2) Where do high or unusual charges come from? (3) What are the differences between actual and budgeted costs? and (4) Which accounts are likely to run over budget (and how should resources be allocated to avoid that overrun)? The respondents criticized the reports with the following six reasons:

• Information overload: the report has too much data.

• Overly narrow content: it does not give a big enough picture of cumulative months.

• Random data: it does not group or emphasize data for easy interpretation.

• Unprocessed data: it does not calculate key relationships such as variances between actual and budgeted costs.

• Unintelligible data: it labels rows or columns with terms that have unclear meanings.

• Unpresentable data: it has low legibility and layouts with little difference between figure and ground.

Some respondents rearrange their information in some ways, but six of the respondents rearrange their report either on their own PC or in the interface program. These six are considered writers as well as readers. The other respondents believe they lack the technical knowledge to reorganize their reports.

DISCUSSION

Most respondents felt that they lacked the technical knowledge to adapt the software or applications to their specific needs. They need to know how to translate their rhetorical aims into a technologically produced document.

To develop effective reports, writers must learn the database capabilities that enable them to achieve their rhetorical aims for invention, arrangement, and delivery.

The Aims and Processes of Invention in Data Reporting

The success of data reporting depends on fundamental invention processes, namely writers becoming familiar with a subject, identifying issues and questions that concern readers, understanding the optical orientations that address these concerns, and selecting content accordingly.

The respondents’ unhappiness with the report can be traced to many invention issues. The report does not select and display key data relevant to their needs. Many of the respondents wanted other content as well, such as more verbal description about purchases. The report writers need many technical competencies in database applications, but databases are one of the most complicated technologies for lay users to manipulate for their specific purposes. Writers also need to understand if the connections among data that make sense, practically, for solving a business problem are technically feasible. It is only feasible if the data are set up in a special way to allow writers to retrieve data from different databases.

Once the databases are created, report writers have to know how to frame their searches for information in statements that a program will accept and process. Writing search statements involves abiding by the syntax of a program and, at times, becoming creative with its search logic.

Finally, report writers’ technological strategies include assessing whether the data they retrieve are in fact the right data for their purposes. Database users rarely check the answers yielded by a search “failing to search for other levels of data which could supplement or contradict what they already found.”

The Aims and Processes of Arrangement in Data Reporting

One of the greatest challenges for report writers is to choose an appropriate organizing logic for tables that are multifunctional. They need to know that data reports for marketing purposes may take as many as five drafts of a table before a report convincingly shows a supervisor that it is best to target a very small group of low-volume customers because they generate the highest revenue.

Rhetorical purpose should determine whether the best display is a table or some other graphic form. The preset order of columns results in separating data that these readers want to compare. The row headings also do not accommodate the “cut into the data” that some respondents want to take because of the unique structures of their projects.

The Aims and Process of Delivery in Data Reporting

Delivering information in effective visual designs involves giving readers easy access to the data and data relationships relevant to their concerns. Reports used for reference usually display large amounts of data in a small amount of tabular space. Legibility is paramount.

Reports used for problem solving need designs that draw readers’ attention to key information and that help them to distinguish important types and groupings of information. Table displays should create for readers’ paths through the table so that readers perceive particular groupings of data as individual “locales” that they may access at random and read as self-contained information. Type size, style and variation are vital for emphasizing specific elements and relationships; positioning and locating data support people’s conventional strategies for reading left to right and top to bottom. Use of white space is important in creating tables that maintain readers’ understanding.

IMPLICATIONS FOR TEACHING AND FURTHER RESEARCH

For invention, arrangement, and delivery, writers of data reports must dynamically relate rhetorical and technological strategies to produce accessible and purposeful tables of information. The effectiveness of data reports, as judged by readers in an actual communication context, hinges on writers having chosen and implemented conceptual and visible displays that answer readers’ concerns and questions.

Mirel suggests introducing undergraduate students to a curricula including technical and professional writing. It would be especially beneficial if the writing and computing teachers could provide some collaboration for the students and can include team teaching to show how both areas cross over.

To better understand the rhetorical and technological competencies involved in data reporting, researchers need to investigate the ways in which various features and functions of database applications enhance or constrain rhetorical choices. More studies should focus on report writers and actual readers in natural work settings, closely assessing the qualities that characterize effectiveness for different types of data reports and the processes involved in producing them. These studies need to extend long enough for researchers to iteratively test writers’ choices and revisions against readers’ actual uses of a document.

Summary of Chapter 8: Barker

by Gary Teagarden and Jennifer Bruns

Conducting Usability Tests

This informative chapter covers usability testing for document and software design.

There are 10 steps in the process of usability testing:

1. Decide when to test
2. Select the test points
3. Choose the type of test
4. Set performance and learning objectives
5. Select testers and evaluators
6. Prepare the test materials
7. Set up the test environment
8. Record information accurately
9. Interpret the data
10. Incorporate the feedback

1. Decide When to Test
You can test at any time during the nine stages of the documentation development process. Usually you test after you have a draft finished so you can see the areas that need testing. But you can test during the three major phases: design, writing or development.

2. Select the Test Points
A test pint 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. Test points fall into two areas: problems with content and problems with document design. Test points could be body text size, heading size, cropped screens vs. whole screens, cues for steps and page orientation.

3. Choose the Type of Test
There are three types of tests—dependent upon the test points selected in step two.
Can-they-do-it test
Can-they-understand-it test
Can-they-find-it-test

4. Set Performance and Learning Objectives
Because you want your tests to measure actual behavior, you must come up with numbers that correlate with the kind of performance you want from your users. These are often called operational objectives. There are two broad categories of performance objectives: Time-related and error-related.

5. Select Testers and Evaluators
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.

6. Prepare the Test Materials
Depending on the complexity of your usability test, the written and other materials you supply for testers and evaluators can get complicated. See Tables 8.5 and 8.6 (P.248-249) in the text for a comprehensive list of potential test materials.

7. Set Up the Test Environment
The environment for your test may range from the user’s work environment (the field) to a controlled laboratory. Your best chance to learn about actual use in the context of the user’s work and information environment comes from field testing.

8. Record Information Accurately
Recommend using voice and video recorders, plus take copious notes so that you don’t miss anything.

9. Interpret the Data
Interpretation requires you to take into account all the elements that can go wrong with testing so that you get clear results.

10. Incorporate the Feedback
Following the interpretation your data then the next step is to incorporate the results into your final design.

The author talks about the test paradox: The earlier you test the weaker the results but the easier it is to make changes; the later you test the better the results but the harder it is to make changes.

Some large companies, such as IBM have full-blown usability labs replete with two-way mirrors, video cameras and eye-tracking devices. Ironically, often the best results from usability testing comes from field testing. In addition, field testing is less expensive. But field research poses issues of time, politics, budgets, ethics, and legality that require you to proceed carefully.

Campbell, Chapter 8, “Did I Forget Anything?”

Introduction
Be thorough! The writer is ultimately responsible for mistakes and errors in completed projects.

Creating a Perfect Document
Be sure that you use a review process to ensure that your document does what you want it to do.
There are five types of reviews:
1. Verification (e.g., accuracy)
2. Validation
3. Editing
4. Proofreading (e.g., spelling, punctuation)
5. Approval (e.g., getting clearance)

It is important to keep in mind that these reviews should be done in the above order so that the most critical issues are addressed first.

Can I combine a review?
You can, and sometimes it is effective. However, sometimes this is a more demanding and requires greater skill from the reviewer. When you try to compress all the reviews into fewer steps, something will usually suffer. If you choose to combine reviews, be sure your reviewer knows what you are really looking for from them – whether it is punctuality mistakes or accuracy of the information – they need to know. Having multiple reviewers is another way to ensure that more errors are found in less time. Failure to plan adequate review time is a guarantee that a document will go out with mistakes in it.

The rest of the chapter describes the review steps in detail:

Verification
• Checking for accuracy – information up-to-date, correct, dimensions accurate, eligibility requirements correct, etc.
• Various methods: compare the final draft to the original draft, check it against source documents, confirm numerical and statistical data, or assign a content expert to do the review.

You can combine them or perform them separately.
• Especially important in procedures, where perfection is vital.
• Sometimes, verification can be combined with editing, but it’s usually best if these are done in a separate review. You must be in an “accuracy” mindset when reviewing facts and important data.

Validation
• Checking for usability – policy or procedure understandable, well delivered, does it work in the real world, etc.
• Make sure the concept is understandable. Read the policy completely through to see if it makes sense or if anything is missing. Some writers can do this themselves, but it is easier if there are at least one or two other reviewers.
• Policies can be difficult to validate, as they’re often ambiguous or hard to measure. Usability testing is the best way to test a policy, so use this when possible. You can watch or gauge your reviewer’s difficulties or confusions and make the changes when appropriate. Honest feedback is important.
• Validating procedures does take longer because you’re actually testing the steps and sequence. Again, more eyes make for a better review. Use walk-throughs, observation, focus groups, and surveys to gauge responses. All of these steps require that you go through the basic steps of preparation, testing, debriefing, and documentation.
• Look for anything that indicates a problem on the user’s part: hesitation, guesswork, rereading, page flipping, or improvisation.

Editing
• Most are familiar with this – once you’re sure the content is correct and understandable, you can move on to editing. Editing presents a unique challenge – improve the policy without changing the meaning.
• Use this review to check for format, wording, consistency, flow, cohesion, layout and visual appeal.
• Number of edits depends on the document and project. Use the number you feel is appropriate.
• Approach editing with great precision. Know what you’re editing for, and plan time to do it. Make sure you are going to be uninterrupted when editing so that you can give the document your full attention.
• Keep an eye out for detail for important matters mechanical correctness, not trivial ones. Be sure that you are not looking for small changes like typographical errors in editing – save that for the proofreading phase.
• Review the page layout, look at the formats, consider the design elements, and scrutinize everything for consistency and logic.

Proofreading
• Proofreading is an important, although not necessarily the most enjoyable, task. Most writers consider proofing insignificant. However, if you do not spend time proofreading your document, you may let small mistakes get through. This can question your credibility with your audience. Consider proofreading your final walk-through of your document.
• Decontextualizing is the secret to effective proofreading. Reverse the learned habit of reading for meaning and concept. Take the letters, numbers, and words out of context and consider them as strictly letters, numbers, and words.
• To proofread, you can try many different methods – read backwards, read aloud, read into a tape recorder, read with a partner, read diagonally, turn the page upside down, photocopy it, scan it, or take frequent breaks.
• Look for every single imperfection, typographical errors, punctuation, spacing, spelling, agreement, page breaks, titles, misplaced words and phrases, alignment, names, numbers, typestyle, typesize, and margins. When proofreading graphics, be sure you view all details – enlarge the graphic, make certain all numbers are correct, every line is plotted accurately, every item is correctly labeled, and the information in the graphic is consistent with the text.
• The most common errors: transposed letters, duplicate letters, omitted letters, and substitute letters. All proofreaders also have their own ‘blind spots’ – know what yours are and make a mental rule so that you can remember what is correct.
• If you choose to proofread your own material, be sure you are very thorough. It’s best, however, to hand it off to someone else to proof if you can.
• All writers have deadlines. Make sure that you always allow some time for proofing, no matter what.

Approval
• Getting clearance is the last step of documentation review. Send your document to the designated approvers when you’ve completed the above four review steps. However, be sure that you keep in constant communication with your reviews throughout your documentation process. Ask for their input, or consult with them if you need to – approvers don’t like surprises.
• It is best to have a formal procedure in place for approving documents. Make sure your procedure outlines time frames and the approval cycle so that there are minimal questions from the approvers. Once these approvers receive a draft, be sure they know you are expecting their input and that all comments will be considered.
• Slow response time is usually a problem. Most managers and approvers are busy, and will often be swamped with other work and your review will just be one extra thing. Strive to make your document approval an easy process by making a form that makes the approval quick and painless. See the sample form in Chapter 8 for ideas.
• Sometimes approvers disagree on documents – don’t let this bother you. Opinions are what you are looking for with your document review, and it is better to get these opinions and thoughts out in the open before the policy is in place and it then becomes more difficult to change. Stay on top of the approval by coordinating and communicating amongst the approvers. Analyze their responses and look for validity and set up meetings if your approvers require one to come to a consensus.
• You can also have unofficial approvers for your document. Frontline managers, group leaders, or even informal clique leaders can be key supporters for the document. Keep these people in mind in your writing and review process as well – always keep those lines of communication open.

The Critical Decision: Who Reviews?
It is always better to have others review your work. Their eyes are fresher and they are not too closely tied to the doc. Sometimes, it is not always possible to have other reviewers, and when you MUST review your own work, you’ll have to exercise twice your normal discipline.

Submitted by Team 1: Beeman & Xiong

Barker, Chapter 9: Editing and Fine Tuning

1. Establish Project Guidelines
Everyone involved should understand their roles for each project, as well as the team goals. A person may be a combined writer/editor, a writer, or an editor. The four types of editing that should be covered in a project are managerial editing, substantive editing, copyediting, and proofreading.

2. Understand the Types of Editing
Managerial editing: Sometimes called the production editing stage, this type of editing involves the documentation planning and production.

Substantive editing: Sometimes called the developmental editing stage, this type of editing involves information and language editing.

Copyediting: This type of editing involves consistency and accuracy in grammar and the document's format.

Proofreading: This type of editing involves giving everything a final look to make sure there are no inconsistencies or errors.

Note: When editing help documents, online testing and editing is important to ensure proper setup of the document on the computer.

3. Plan Your Editing Tasks
Plan and schedule the editing tasks in the early stages of production. Take into consideration the amount of time needed to complete each task when scheduling editing work. Make sure that when editing, no other tasks are performed. It is not the job of the editor to perform any of the writer's tasks, and it could back up the schedule if other tasks are worked on when they shouldn't be.

4. Develop the Appropriate Editing Forms
Develop and use editing forms to standardize editing practices and ensure efficient communication among multiple editors. Of particular importance is the style sheet (a running list of style decisions that have been made for the current document) and the style guide (a higher-level document that broadly defines the style of the document class or organization). Once these documents have been developed, encourage their use.

5. Conduct Editing Sessions
Sooner or later, you will sit down with the document and begin editing. Find an environment that maximizes your ability to concentrate. For most people, it must be absolutely quiet, with no disruptions. Use an editing checklist to make sure you don't skip any editing tasks--especially important when editing your own writing. Try editing with a partner--two brains are better than one. Also consider working on each task for only a short time. Your attention will be less likely to wander. Use multiple, separate editing techniques, rather than trying to catch everything on the first pass.

DISCUSSION

Editing Graphics
Figures and tables are often the first things a user will look at. The editor must ensure that the figures and tables are appropriate and accurate and that they match the document's style. Avoid cluttering screen shots with arrows and callouts--they distract when overused. Ask yourself, Will this figure help the user understand the information? Is there a better way? Know your audience.

Writing v. Editing
Writing and editing are completely separate tasks. If you are the writer and the editor, try to let the document cool off before you begin editing it. You'll need some distance to make unclouded decisions about your own work. If you are the editor of someone else's work, give them suggestions but avoid researching and writing for them.

Crossing Cultures
If your document will be read by non-native English speakers, try to make it easy on them by using simplified English. Simplified English stresses the active voice, the use of articles, the use of consistent language, and the construction of short, direct sentences. If the document will be globalized, used generic language that will be understandable across cultures. If your document will be localized, use language that is familiar to the culture the document is destined for.

When editing for translations, the rules for simplified English apply. In general, try to make it easy on the translator to render the text into a different language. This is complicated and requires specialized training and practice.

Editing Online Help
Editing online help systems is similar to editing paper documents, but there are some differences. Pay special attention to the index and links because these will be used heavily by the average user. Edit on paper and on screen because it is generally easier to edit on paper, but you need to see how the document works on screen as well. Make sure you have an up-to-date topics list so you can check the completeness of the help system.

Knowing What's Correct
Much of the time, you won't. Consult various authorities to arrive at a consensus opinion, then stick with it. Above all, ensure that your document achieves the document's goals.

Working with Others
1. Be Positive; Don't Be a Pain in the Neck
2. See #1.