Rockley, Chapter 2 Summary - (Haupt)

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)

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)

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

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:

1. Content silos are a result pressures and structure of an organization.
2. The content process itself is one that often occurs in isolation which creates many inconsistencies and possibly extra work.
3. Poor communication can happen when one group fails to inform another group that something has changed.
4. 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.
5. 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.
6. 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.
7. 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.
8. Product support materials can form a continuum that takes you through marketing materials through training, product support, troubleshooting and problem solving.
9. A company's web site represents key information and unified content strategy ensures the web content is managed effectively.
10. 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:

1. It is recommended that writers learn the principles in Chapter 3 and use them to adjust various guidelines as needed.
2. Of the presentation principles, the text-graphic format is the most effective application when working with step-by-step instructions.
3. Chapter 5 covers the ground rules for graphics.
4. Chapter 6, Language Control, covers the text portion of the format.
5. Fixed list command verbs are required with the use of the format.
6. Chapter 6 contains a basic list of 87 command verbs and definitions.
7. 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.
8. Writers will sometimes work with subject matter experts which results in the responsibility of the instructions to be shared equally.
9. Chapter 8 also provides a systematic way to develop procedures.
10. 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)

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)

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)

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)

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)

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

My first Blog.

Hello

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.

Emma's Intro

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.

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!

An Introduction

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

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.

Welcome to the Engl476576 blog

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.