Doc in the Age of Throwaway Technology

A coworker of mine was having trouble with her PC when I suggested she reboot to see if that would help. When she e-mailed me to tell me that the reboot worked, I replied:

the manual should just say "reboot. if that doesn't work, buy a new one. they are not that expensive anymore."

I was joking (manuals provides more than troubleshooting information, and many manuals don't include troubleshooting information at all), but something about those words seemed profound. What will be the effect on documentation as the cost of ownership for computer software and hardware continues to trend down?

Not only will it be cheaper to replace hardware when it breaks - already you can buy a fairly powerful new desktop machine for under $400 - but the cost of replacing software that you can't figure out, don't like, or have outgrown is likely to shrink as well, or become entirely free. This creates three problems for businesses and doc people:

1. It will be cheaper than ever for users of a technology to walk away from a weak product, even after they have invested money in an initial purchase.

2. Learning how to use a technology will be the only barrier to entry for users seeking to switch technology.

3. (The result of one and two) Learning how to use a technology will be the biggest investment a user makes in new technology.

Technologies that are powerful, easy to learn, and rewarding to use will succeed. For these reasons, quality documentation will become more important than ever in the Age of Throwaway Technology.

Good docs make more powerful products
Documentation unlocks the hidden power of technology. If you've ever worked for a technology company, you know that the products are capable of doing far more than the average user uses them for. Part of the reason for this is that users don't know or understand the full capabilities of the product. Good documentation makes the user aware of things that can help them, without requiring the user to know what it is they don't know. Customization Guides, Hacker Guides, and the Missing Manuals series focus on this kind of information. The Web is also a great source of information about things you can do with products that aren't included in the manuals; in some cases, the makers of the product don't even know how their product ends up getting used by enterprising users.

Good documentation can help people get more out of their products than they would discover on their own.

The alternative in the Age of Throwaway Technology: If a product doesn't instantly seem capable of doing what the user wants, they may give up and try another product.

Good docs make products easier/cheaper to learn
Documentation is the cheapest way to learn something new, and, unlike training, it is always around. Well produced documentation can answer questions, anticipate user needs, offer suggestions, and lead the user down a path to success. Documenation can be used by beginners and experts and can be used to hold a users hand or as quick reference. As documentation technology advances and incorporates innovations in other fields, the ability of documentation to respond to users' needs will only get better.

Good documentation fills the gap between interface design and user experience. Even in the most expertly designed system, users will always have questions, and good docs can answer them.

The alternative in the Age of Throwaway Technology: If a product requires a lot of face-to face training or the docs seem disorganized and incomplete, the user will be unable to afford the investment.

Good docs create a richer user experience
In a world where technologies come and go, many users are reluctant to put in the time to become an expert in any one technology. This means that they learn technologies as they go. In the world of computer software, for example, users explore the user interface, click buttons, and try different functions to see what works for them. Documentation that is aware of how users explore and use technology can make this experience richer by meeting the user half way. If the users are seeking expert information and actively seeking out the docs, the technology can bring the doc to the user, thus offering them the rewarding experience of "learning through exploration."

Documents that are there for users when they need them and unobtrusive when they don't can create a richer user experience and customers that are less likely to give up on your product at the first sign of trouble. The documentation becomes the trusted voice of the technology.

The alternative in the Age of Throwaway Technology: If a product's documentation does not fit the way people use technology, it will be ineffective at teaching the user about the product and users will seek a product that they can learn from and feel comfortable with.



While it may be a good thing for users/customers that they can walk away from "broken" technology, it's not a good thing for businesses whose job it is to retain customers. In order to attract customers, products must be cheap, powerful, and easy to use. For customers, as their investment in the software or hardware declines, the relative investment in the support for those products (including the documentation) increases. As this investment in documentation increases, so do the expectations for return on that investment. To alleviate these concerns, the doc experience must become a major part of the overall product experience, and the product experience must be positive.

March Madness: Doc Edge Goes to School

Tonight, the NCAA's round of "Sweet Sixteen" in the Men's Division 1 Basketball Tournament gets underway. This years Sweet Sixteen is no different than previous years - there are big schools, small schools, well-known schools, and unknown schools; schools with big repuations, and schools with not so big reputations.

This unpredicatble mix of our colleges and universities provides a good opportunity to survey the variety of technical communication-related programs being offered around the country. These programs can tell us a lot about the current state of doc, and where it is headed in the future. Afterall, a major role of our colleges and universities is to identify changing trends in the market and to serve those trends by preparing the next generation of dreamers/thinkers/doers with the required skills.

The following is a break-down of the Sweet Sixteen matchups based on the "edgy-ness" of the chosen doc-related program (If I've missed a program offering that you feel should have been mentioned, please let me know). Unlike the real tourney, we'll decide the Final Four and the National Champion before this post is finished.

Duke vs. LSU
Duke's program on Information Science and Information Studies offers Bachelors and Undergraduage Certifcate studies whose mission is to "... study and create new information technologies and to analyze their impact on art, culture, science, commerce, society, and the environment." The description for an introductory course asks "How have emergent technologies such as videogames, podcasting, digital animation, Friendster, Google, virtual reality, and Grokster transformed the ways in which we relate to information?"

LSU's Cognitive Science Group offers courses in Biology, Computer Science, Communication Science and Disorders, Curriculum and Instruction, Engineering, English, Information Systems, Philosophy, Psychology and more. In addition, the Cognitive Science group holds brown bag sessions that focus on special topics, and feature a special speaker. One topic: Cellphone Distractions and Working Memory.

Winner: Duke

West Virginia vs. Texas
West Virginia's programs in Technology Education offers a Masters of Arts and a Doctoral degree. Masters program courses include Computer Mediated Communication, Web-Based Instructional Design, Instructional Technology Integration, and Contemporary Problems in Communication.

Texas' School of Information defines its values this way: "At the School of Information, we are committed to making a difference in the lives of citizens by enabling and supporting the curation, organization and experience of information in ways that enhance lives." The name of the school was changed in 2002 from the Graduate School of Library and Information Science to School of Information to "better reflect the diversity of issues and the multidisciplinary nature of the studies in the information field." The school offers Master's, Certification and Advanced Study, and Doctoral programs (as well as several undergraduage courses). The School of Information is ranked among the 10 best LIS schools in the nation by US News and World Report.

Winner: This was the best matchup of the bunch... I'll go with Texas.

Memphis vs. Bradley
Memphis' Department of Communication offers undergraduate studies in three concentrations. The general communications concentration prepares students for the "wide variety of opportunities available to communication professionals and/or for graduate education" by "integrating philosophy, theory, history, criticism, research, ethics, and practice." New curriculum has been added that addresses the growing field of health communication. Masters and Doctoral degrees are also offered.

Bradley's Multimedia Program focuses on "creativity and conceptual problem-solving." Course include Multimedia Authoring, New Media Theory, and Designing for the World Wide Web. Anti-Alias is a student-run organization made up of Bradley's multimedia students. Last year, Bradley's multimedia students worked on a project to rebrand the program. The new slogan: "Constantly evolving, Always innovating, Purely original."

Winner: Bradley

Gonzaga vs. UCLA
Gonzaga's Communication Arts department offers a Public Relations major whose objective is "to provide students with a critical understanding of the symbolic, rhetorical behavior which creates and influences relationships between organizations and their publics. Courses encourage the examination of practical and theoretical perspectives, historical developments, research methodology, legal applications and the expanding role of Public Relations in modern society." Courses focus on journalistic writing and public affairs.

UCLA's Design Media Arts department describes Media Arts as "a new field that represents the exciting convergence of technology with the established design discipline." The department's factulty focuses on "...educating responsible designers and artists for the information age by teaching the fundamentals of Design, Media, and the Arts, and encouraging experimentation and innovation." Students are exposed to such new media concepts as interaction and interface design, ubiquitous computing, virtual environments, and information spaces to name a few. Undergraduate and Graduate degrees are offered. One undergraduate class, Design for Environmental Communication, focuses on "...aesthetic issues concerning creation of design elements incorporating concepts of spatial dimension, human/environmental scale, motion, and time."

Winner: UCLA

Connecticut vs. Washington
Connecticut's Communication Design program offers a Bachelors of Fine Arts. The program's Web Site describes the key competencies of Communication Design as the "...ability to identify, research, evaluate and solve problems, to create prototypes, to apply relevant tools and technologies, to understand basic business organizational practices, and to apply an understanding of design history." Students in Communication Design are encouraged to seek out courses in communication theory, writing, psychology, sociology, anthropology, linguistics, and the humanities.

Washington's Technical Communication department is part of the College of Engineering and includes a number of programs including Undergraduate, Day and Evening Master's, PhD, and Certificates in User Interface Design, Technical Writing, and Multimedia. The program "strives to equip its students to be leaders in designing the future of communication." In addition to the traditional tasks of technical communication, the program's literature declares that "increasingly, technical communicators also help create technical solutions to communication problems—organizational content management systems, personalization systems, ‘information supply chain’ analyses, automated tools for usage data collection, dynamic documentation, and other cutting-edge solutions to communication challenges." A global awareness is also apparent - the department offers programs in Technical Japanese.

Winner: Another close call, but I'll take Washington.

George Mason vs. Wichita State
George Mason's Instructional Technology Programs are offered by the College of Education and Human Development. PhDs and Master's degrees, along with Graduate Certificates and undergraduate courses are offered. The Instructional Design track for the Master's degree accommodates students who "...would like to gain the knowledge and skills to design and develop technology-supported instructional and training solutions for the public or private sector." Courses offered within the programs include Web Accessibility and Design, Instructional Technology Foundations and Theories of Learning, Human Computer Interface Design, and Tools for Visual Design.

Wichita State's Graduate Program in Human Factors Psychology is a PhD program that trains human factors psychologists, whose job it is to "apply [their] knowledge to the design, operation, and maintenance of machines, systems and environments so that optimum performance can be achieved....Among the goals of human factors psychology is making it easier and safer for people to use machines such as cars, airplanes, and computers, as well as improving home, work, and leisure environments." The program sponsors several Human Factors Laboratories including the Human-Computer Interaction Lab, the Instructional Technology Research Lab, and the Software Usability Research Lab.

Winner: George Mason

Villanova vs. Boston College
Villanova's Department of Cognitive Science "offers a course of study related to intelligent systems with particular emphasis on the perspectives of cognitive psychology, computer science, philosophy and biology." Cognitive Science has evolved to ask such questions as: How a computer can beat a world champion in chess? Why do diseases such as Alzheimer's and schizophrenia disrupt thought? And, why is it so hard to program a VCR? Courses include Human Computer Interaction, Information Visualization, Cognitive Psychology, and Introduction to Artificial Intelligence.

Boston College's Communication department offers undergraduate courses in World Wide Web and Digital Media, Visual Design, Human Communication Theory, and Health Communication. In addition, the more traditional offerings in the department offer students general exposure to "study, criticism, research, teaching, and application of the artistic, humanistic, and scientific principles of communication."

Winner: Villanova

Florida vs. Georgetown
Florida's Digital Arts and Sciences program "crosses college boundaries between engineering and fine arts." Students take Art and Computer classes at the same time. Artistic technique, graphic design, and 3D modeling are the focuses, but courses are offered in Programming, Computer Organization, Professional Writing, and the Humanities. Class projects incorporate team work and multimedia productions.

Georgetown's Communication, Culture, and Technology Program focus on cultivating an understanding of "...the role that technology plays in our lives -- from how we shop to how we form our identities." The program offers a Master of Arts degree "for people who want to combine their academic interests with studies of the history and future of technology." Areas of study include Technology and Information Policy, Media, Art, and Representation, Technology, Business, and the Economy, and Issues in Globalization.

Winner: Georgetown

Not a bad selection of programs considering that these schools are here for their ability to put together basketball teams, not necessarily for their quality or quantity of doc-related offerings. Imagine if we hand-selected the top 16 schools in this area! (Maybe I'll do that some day.) Clearly there is an increased focus and need for a better understanding of information and how it is presented.

Oh, and the final results are in...

Final Four: Texas, Duke, Washington, George Mason.

Champ: Washington

What are Edgy Docs?

Doc Edge is all about producing Edgy Docs. Edgy Docs give your product an advantage over other products, while pushing beyond the standards and limitations of traditional documentation.

Throughout the life of the Doc Edge blog, we will talk a lot about what goes into Edgy Docs, and give plenty of examples. For now, I will briefly discuss some of the basic characteristics that Edgy Docs should exhibit. Some of these qualities relate to each other, and some would not be possible without the others. (Not all great docs will exhibit all of these qualities, but the perfect doc would incorporate these, and perhaps some other qualities, flawlessly.)

Edgy Docs are:

Structured -- Structured docs define themselves. They make it easy to search for data, reuse data, and stylize data based on context. Most document structuring is done using XML. Structured docs open the way for non-book, non-help based forms of documentation. Docs integrated with the application, that allow people to explore the UI and learn from the docs at the same time. Structured docs lead to improved maintenance, better issue tracking, and a more consistent look and feel across a product's documentation set.

Swift -- Swift docs can be produced, delivered, and updated quickly. Swift docs make use of automation, reuse, and single sourcing. Swift docs are never out of date and can be printed on demand. If you are writing a Swift doc, you are doing so in an Agile environment, without specs, and you are considering all possible options to add value to the product; you are not assuming that the best you can do is fill a PDF with words. Swift is not just about how the doc is produced and maintained, it is also about how the user interacts with the doc.

Smart -- Smart docs leverage the collective knowledge of all the disciplines related to communicating information. Information design, graphic design, the teaching profession, web site design, usability, journalism, and so on. Smart docs also have an awareness of the user and his or her needs. Smart docs may suggest answers, point users in the right direction, or do something special to help the user remember something they have forgotten in the past. The smarter docs get, the more they become learning tools and applications.

Shared -- Everyone has access to Shared docs, and everyone has the ability to customize or create their own Shared docs - even customers. Shared docs contain all the knowledge about a particular product. Shared docs allow for online review and editing, even after the doc has been released. Shared docs create opportunities for users to be active participants in the documentation feedback loop and to customize the documentation for their own needs and perhaps add something that the original author didn't anticipate was necessary (or even know was available). Finally, shared docs can be shared with everybody across the globe. Mutliple languages and character encodings are supported through the use of translation-aware authoring and standards-based authoring tools.

Saleable -- Saleable docs impact the bottom line. At the very least, they are so Structured, Swift, Smart, and Shared that they save money. But, more importantly, the make money. Saleable docs can make money in one of two ways. First, documentation will become a major differentiator in the globalized, advancing world as more and more things become commoditized. For this reason, it is important to have a reputation as a producer of quality documentation that users can and do read, thus making them more productive in their real jobs. Secondly, Edgy Docs can actually create revenue. Because people want to read Edgy Docs, they are willing to pay for them as a useful service, perhaps subscribe to them, or even buy them from a third party publisher who licenses the information. As the age of open source software rolls on, software companies may one day be giving away all the software and making a good portion of their money on the documentation, or at least parts of it.

So, there they are. The 5 S's of Edgy Docs. Until we come up with another S, all of the ideas and documents discussed on Doc Edge will relate to one of these 5 categories. If you've got any other ideas, please send them along.

Goodbye to RTFM

I worked as a technical writer for 4 years before I heard (or at least recognized) someone use the initialism RTFM. I don't know how that happened. People I work with don't know how that happened. It just did.

If you don't know - and from what I hear, it is not possible to not know - RTFM stands for Read The ... um ... Funny Manual.

RTFM is used in and around software companies in response (both spoken and unspoken) to both internal (spoken) and external (unspoken) people who ask questions or seek guidance for something that is covered in the documentation. RTFM's cousin is the less alphabetical "It's in there somewhere." I call that check mark documentation - "I wrote something about the new drivers on pg. 56, check."

I'd like to think that my lack of familiarity with this term has something to do with my approach to documentation. That approach being that is my job to make it easy, attractive, and fulfilling for people to RTFM. The fact that people are turned off by the idea of reading the manual is something that drives my thoughts on the subject of documentation. The fact that people are often unable to find what they are looking for when they do read the manual is a challenge I try to address daily.

Why do we need to tell people to read the manual? They know it's there. Why do we have README files? Does this imply that the other doc files should not be read? Maybe this is why people don't read the manuals. Doesn't popular psychology tell us that people might respond better if we named the file DONTREADME?

People don't have to be told to do things that make their lives easier. We don't have an acronym for telling people to use the software. When they learn that the software can help them accomplish something, they use it. People don't have to be told to turn on the heat in their homes. They do it because it makes their lives more comfortable. That is what documentation should strive to do. Until documentaion consistently delivers what people want, people won't use it.

And, it's not enough that the information the user is looking for is in the manual. The job of a technical communicator does not end when all the words about a particular product are assembled into a PDF file. The presentation of information must lead the users to the information they want - even bring it to them. Just saying "It's in there" is not enough. Why didn't the user find it? Why wasn't it obvious that this was the information they were looking for? These questions can't always be answered (users do make mistakes), but striving toward answering them and minimizing opportunities for mistakes is where there is value.

An additional challenge comes when trying to address the needs of both beginners and experts. One article about RTFM states it this way:

"When evaluating whether it is acceptable to express sentiments like RTFM, one must consider the trade-off between maintaining the usability of an Internet forum for its existing users, and making a forum welcoming to newcomers."

Rather than a trade-off between one or the other, I put the onus on the technical writer to accommodate both types of users through some speical organization or innovation in documentation. Those are the kinds of innovations that can make our jobs more valuable and exciting, and can push documentation over the edge.

RTFM may have come to popular use in the hacker community, where people are willing participants in a quest to learn all they can and implement that knowledge in novel ways. Perhaps, in that setting, RTFM is the right sentiment when someone asks a question that is documented somewhere. But, when documenting a product that is indirectly important to the people using it (i.e. it helps them get something else done), RTFM is always the wrong response.

The information that comes with a product, and the task of processing that information, is part of the experience of using the product. That experience should be a positive one. Not one that we should curse at people to take part in. Ultimately, it is our problem.

Good Doc is a Hit Record

I came across an article about what makes a hit song today, and it struck me that popular music has a lot of the same characteristics as good documentation, or Edgy Docs. Basically, the article identifies the following characteristics of a hit song:

• Recognizable, listener(user)-friendly structure
• Important/dramatic components are strategically placed
  
• Simple language and melody, memorable
  
• Contains a focused thought that people can identify with
• Presented flawlessly and with distinction
  

The article describes one hit song in the following way:

"The melody and lyrics are distinctively simple and presented faultlessly by [the singer's] amazing and distinct voice. But the song is also universal -- quickly connecting with most listeners."

The author goes on to talk about the difference between expression and communication in music. To summarize: expression is the Avant-Garde Jazz CD that you pretend to like in order to seem interesting. Communication is that boy band song from 5 years ago that you still can't get out of your head. Unfortunately, or fortunately (Justin Timberlake gets more dates than John Zorn), I think documentation is supposed to be most like the boy band song.

Good documentation doesn't want to rock the boat, it doesn't push the boundaries of expression, or create new conventions for communication. It wants to be catchy, to be accessible, and to communicate.

That does not mean that good documentation can't make use of new technologies or new models of communication. In fact, this blog will spend a lot of time talking about bringing new methods and technologies from other fields into the world of documentation - to push documentation over the edge. But, the focus must always be on communication and accessibility.

The Beatles would have written good documentation. Many people consider the Beatles pioneers in music production, and certainly they were commercially successful. But, when you look closer at their music and the music of their time, you see that they weren't the ones who were really pushing the boundaries of musical expression. In fact, their sound was quite conventional compared with the real "expressionists" of the time.

What the Beatles did was borrow the right amount of new technologies, new musical conventions, and new philosophical ideas and mix them with accepted practices. They successfully communicated to a generation and counting (over a billion records sold!) by being accessible and interesting at the same time. Universal, yet distinct.

If your documentation is half as universal and two-thirds as distinct as the Beatles' body of work, you are on your way to documentation greatness. And, if you're looking for a good tech writer, I think Ringo Starr might be available.

"Pubs people" change the future of the PC

Here's a video link that illustrates quality documentation work. No booster-seat manual, just an understanding of a problem the user faces and some investigation into a solution. Simple.

Starring: David Bradley and Bill Gates. Bradley gets a laugh at Gates' expense.

What is Doc Edge?

Doc Edge is a blog about today and tomorrow in the world of technical communications. I am hoping that an enthusiastic and forward-thinking blog about how to create and deliver better documentation now and in the future will excite many technical communicators who are ready to break out of the old and older way of doing things that just don't work.

My reason for starting such a discussion on a topic most people feel is a necessary evil? I don't believe documentation needs to be a necessary evil, and more over I believe it will become a major way in which technology companies differentiate themselves in a more and more commoditized technology market. Good documentation can save and make money!

The "Doc" in Doc Edge is a reference to the word "documentation," not the word "documents." The job of technical communicators who create "edgy" documentation is to fill the gap left between sensible interaction design/ideas and sensible users/readers, not to create great documents. That is to say, documents need not be part of great documentation. In fact, great documentation may be able to greatly reduce the needed number of documents (both paper and online).

The definition I will present for the word documentation in our context comes from dictionary.com:
"The organized collection of records that describe the structure, purpose, operation, maintenance, and data requirements for a computer program, operating system, or hardware device."

Notice it mentions nothing about printing or documents. In fact, the same online dictionary contains the following "jargon" definition:
"The multiple kilograms of macerated, pounded, steamed, bleached, and pressed trees that accompany most modern software or hardware products. Hackers seldom read paper documentation and (too) often resist writing it; they prefer theirs to be terse and online."

...the definition also mentions "tree-killer" and "tree-ware." Not exactly high praise for something many of us spend lots of time and money on (That's a preposition at the end of the sentence. A rebel technical writer - it goes along with the "edgy.").

I am tempted to use a more generic (and more esteemed) definition for what technical communicators do: publishing (as in technical publications). Dictionary.com defines publish as "Communication of information to the public." At the core, that is what our main goal should be. But, this definition doesn't seem to capture the work of tailoring that information to a specific audience and to a specifc purpose.

I include these words and their definitions because these are the types of things I thought about when trying to come up with a name for this blog. I thought to myself, what word captures what it is I like about what I do, and what words conjure thoughts of all the things I don't like (and want to change) about what I do. There was no perfect way to express this. Doc Edge is what I've got. It's Doc - kind of meant in the way I've tried to express here - and Edge, which indicates that the blog should talk about some interesting, provocative, edgy ideas about ... Doc (if I can think of any).

In my future posts, I will refer to "edgy docs" as docs that embody the types of things we talk about in this blog. Quickly, edgy docs are docs that people want to use, that people can easily use, and that save, make, or save and make people money. In my next Tuesday post, I will begin to talk more about the characteristics of what I call "edgy docs."

One of my goals for this blog is to develop more deeply the ideas behind Edgy Docs with the help of the Doc Edge community. Anybody out there?