Principals of Technical Communication and Design - Literature review Example

Technical Writing Critique Introduction With the advent and explosion of the internet within mainstream contemporary society, the necessity of technical writers to produce highly readable and user-friendly instructional manuals and designs has never been greater. While there is no official formatting bible for technical writing and design, writers and researchers have identified a series of effective characteristics of technical communication. This essay analyzes the degree to which these methods are effectively implemented in three published technical manuals: Flash 8: The Missing Manual, Adobe Photoshop 7.0, and Microsoft Word 2003. Flash When constructing technical documents one of the most important things to consider is the knowledge level of the audience (Hargis 2004). As most readers consulting your documents are doing so because they have experienced technical difficult with the application, they desire quick and apt solution to their problem, without unnecessary information. In regards to Emily Vander’s Flash 8: The Missing Manual (2006) the reader is assumed to have no prior knowledge regarding the application. Indeed, the book’s forward aptly begins with a historical overview of Flash, describing how it has evolved since its early usage in professional animation and how now everyone with access to a personal computer has the opportunity to learn web animation. Vander (2006, p 3) states, “You don’t have to be a professional artist to create useful animations with flash…all you need are this book and an idea of what you’d like to create.” However the text does consider the more experienced user, as it differs between different versions of Flash – the amateur and professional models – and explains the software updates that have been included in the newest version of Flash. The book is modeled much in the same way as the For Dummies series, with a similar reader in mind, as the introduction makes clear with its use of friendly and inviting terminology. In describing the difficulty of Flash, Vander (2006, p.3) says “It’s hard than a greased tightrope.” While such colloquialisms may not be appropriate for high-level programming guides, it functions excellently in this context as the reader is not only engaged and entertained, but comfortable in quest to learn the foundations of Flash animation. Another important feature to consider when analyzing technical manuals and documentation is their structural layout. In Alder (2003) differentiates between varieties of forms of structural layout and describes the methods in which they are most effective. According to Alder, the main structural forms of technical documentation can be broken down into hierarchical, horizontal, vertical, linear, and non-linear functions. Vander’s Flash 8: The Missing Manual (2006) exhibits traces of these functions in different ways to construct a highly functioning and usable manual. The hierarchical forms of organization assume that certain information is more valuable to the reader than others and structure the text in a way where this information is made available first, and then followed by information that is contingent upon it. Vander effectively uses hierarchical forms of organization throughout her book to aid beginning users gain a complete understanding of the technical processes at work. We see this in a number of regards beginning with the introduction that gives a broad overview of Flash’s functionality. The first chapter titled “Getting Around Flash” follows from this and offers the readers a general tour of specific features in the program and outlines unfamiliar terminology that must be processed by the beginning user to proceed with their technical understanding of the application. Once the basic program tools have been established, Vander proceeds to the second chapter titled “Creating Simple Drawings” which introduces readers to a tutorial on one of the foundational aspects of Flash animation. It’s an apt and effective second chapter in its incorporation of hierarchical structure in that Flash drawings inform all future uses of the program. The third chapter titled “Animating Your Drawings” continues the hierarchical structure as it effectively builds on concepts covered in the first chapter to continue informing the user on the foundational levels of technical proficiency. Within each chapter, Vander makes great use of subsections to further develop the predominantly hierarchical structure of her manual. For instance, the second chapter is divided into: ‘Planning Pays Off’; ‘Preparing to Draw’; ‘Creating Original Artwork’; ‘Copying and Pasting Drawn Objects’; and ‘Adding Color’. Upon inspection of the sections, they seamlessly transition sequentially, equally building the user’s knowledge and technical proficiency like bricks going into constructing a house. Vander’s use of titles is also extremely effective. As the beginning user is still relatively unfamiliar with the terminology and technical functioning of Flash animation when they are reading the second chapter, Vander uses titles that reference no platform specific terms, instead focusing on inviting and user-friendly colloquialisms, such as ‘Planning Pays Off’ instead of ‘Structure and Organizational Flow’ or something similar. As the book progresses, and the reader is assumed to have attained a functional grasp of foundational concepts and vocabulary, the section titles show an equally increased level of technical terminology. For instance, the book’s forth chapter has the subsection titles: ‘Working with Frames’; ‘Adding Content to Multiple Layers’; ‘Viewing Layers’; ‘Working with Layers’; and ‘Organizing Layers’. For beginning users, the book’s reference to ‘frames’ and ‘layers’ would be an inhibiting proposition, but Vander successfully addresses these concepts in the preceding chapters and her incorporation of them here is structurally sound and actually efficient in reminding and educating beginning users of their meaning. Vander divides the book into parts, the second part of which she titles “Advanced Drawing and Animation”. This transition and division functions hierarchically in that the fourth chapter “Organizing Frames and Layers” is the logical progression from foundational drawing techniques, as it incorporates means by which these drawings can be incorporated into sequential units, it also is an excellent use of horizontal structure. Horizontal structure has been defined by Cooper (1998, p. 27) as, “emphasiz(ing) the dependencies within the process. One thing follows another. At the same time, it shows that you may start the process at a variety of points.” This is evident and made great use of by Vander in the division of the book into parts, exemplified in chapter 4. The division in the book is effective in that it allows more advanced users to pin point the position of their difficulty and immediately troubleshoot their problem without having to be burdened by the unnecessary information contained in the proceeding chapters. While beginning and advanced users alike will find Vander’s Flash tutorial highly informative, some might argue it doesn’t contain enough contingent interactivity. That is, while it clearly and effectively explains the concepts, it lacks a supplementary platform that would allow the user to practice the instructions with direct instructional feedback. A more effective manual would contain this supplementary software, wherein the user can carry out tasks described in the books and upon encountering difficulty the software could refer them to specific categories or subsections in the book to reference. Instead, the user is left carrying out the instructions without the ability to negotiate meaning on a higher level. Photoshop Whereas Vander’s Flash 8: The Missing Manual (2006) adheres to a predominantly hierarchical structure, the Adobe Photoshop 7.0 (Adobe 2002) manual, developed by the actual programmers and writers at Adobe, relies more heavily on vertical organization. As a result, the book reads much more like an encyclopedia, with each chapter containing its own individual world of organization. While the opening chapters begin with introductory information, titled respectively -- ‘Using the File Browser’ and ‘Basic Photo Corrections’ – the remainder of the manual trouble shoots specific categories of difficulty. For instance, later chapters include sections ‘Reusuable Flash Symbols and Templates’; ‘Retouching and Repairing’; and ‘Basic Pen Tool Techniques’. It seems that in developing this manual the Adobe writers assume a slightly higher level of technical proficiency on the part of the reader than Vander’s Flash manual. It also is effective in allowing the reader more room for experimentation, as rather than directly stating what the function of the platform is to be used for, as in Vander’s manual, it merely explains its technical use and leaves the reader to fill in the functional applicability. The extent to which this method of explication is effective is debatable. While the encyclopedic breakdown of topics is well structured, it lacks the user-friendly narrative quality of Flash 8: The Missing Manual (2006). As a result, the overall ease of use of the book itself is somewhat hindered. However, with the complicated and multi-uses found within the Photoshop platform, one must question if it would ultimately be possible to structure its technical manual in such a narrative friendly, hierarchical way. Indeed, much of the effectiveness of Photoshop is its means to operate in a multitude of ways, for a multiple number of creative purposes. It seems that the Adobe writers effecitvely took this into account when constructing the manual and left significant room for user interactivity and involvement. The format of the book is further aligned with the use of the Photoshop program when considering the beginning of each chapter heading. The book includes at artistically rendered image at each chapter heading along with a quote in italics that thematically embodies the lesson in the chapter. While the book eschews the hierarchical narrative of the Flash 8 manual, it is effective in engaging the reader through this symbolic occurrence. Adobe manual is effective in that it incorporates an Adobe Photoshop Classroom in a Book CD that supplements in superb part the topics covered in the manual. This was the largest deficiency in the Vander book, and works effectively in the Adobe manual by allowing the user to more actively engage with the explanations and software. Many writers, including Hestal (2008), discuss the overall effectiveness and necessity of incorporating increased levels of user interactivity into technical writing; as users are becoming increasingly technically and visually literature, and more is gradually known about individual learning styles, the need for technical writing to go beyond words, and involve pictures and more effective means of user-interface is abundantly clear. This methodology is put to great use, as the opening of each chapter instructs the reader to insert their CD and open a specified lesson. The CD functions by the user following the instructions in the Adobe manual and replicating them on the CD’s classroom template. The user is even given a time estimation onto how long it will take them to complete each individual chapter section, significantly increasing the manual’s functionality. Whereas Vander’s Flash 8 manual is modeled largely after the For Dummies series, the Adobe manual is reflective a more complicated technical document. Barker (2004) discusses the importance of developing a persona in technical writing that is as close to the personality of the reader as possible. In this regard, the Adobe manual lacks the colloquialisms that cyclically recur throughout the Flash manual. Instead, it assumes a more objective and austere tone, including words such as ‘documentation’, ‘calibration’, ‘electronic files’, and ‘Adobe Task Manager’ in the introductory chapter. It also instructs the reader that it be necessary that have general computer knowledge before proceeding with the manual. While this seemingly conflicts with the persona style that Barker encourages, when considering the audience for the manual one can surmise its effectiveness. As Flash is frequently used by a wide array of people for developing movable website graphics, the necessity of addressing the readers with such a broad and inviting persona is essential, as well as an effective means of selling manuals – people prefer light reading to scientific. Conversely, the readership of the Adobe Photoshop 7.0 manual, particularly the advanced features predominantly featured in the book, are more artistically or technically inclined. As a result, they may feel put-off by the levity and colloquial tone of the Flash manual and be more effectively engaged through the austere objectivity in which the Adobe writers employ. Furthermore, as an official Adobe manual, its structure and tone reflects the company and platform itself, so that by adopting a more light tone, the user may be led to believe that the product is incapable of meeting their highly technical demands, resulting in their adoption of seemingly more technically advanced software. In this regard, the Adobe writers are highly effective in creating and balancing a manual that is as explanatory as it is respectable and objectively clear. There are instances throughout the book where this methodology and approach can be said to fall shot. For instance, in the opening chapter the book already assumes the reader has an intermediate knowledge of technical terminology. As a beginning user of Photoshop, I personally had difficulty comprehending a number of references and believe the writers should have given more preliminary investigation into their explication before proceeding with more complicated features of the platform. For instance, when discussing features and processes related to the Adobe Photoshop Classroom in a Book CD, the writers immediately begin by referring to terms such as ‘palettes’, ‘command settings’, and ‘color calibration’. While these are basic Photoshop terms to experienced users, people deficient in computer literacy will assuredly struggle to uncover their meaning, in many instances being required to consult another book or internet source for their definition, further delaying the response to their question. The individual lessons are structured in a relatively non-dense format, with bolded headings, followed by text, numbered instructions, and italicized points. Graphics accompany many of the textual instructions. While the Flash 8 manual included full monitor graphic explications, the Adobe manual features aggregate graphic descriptions. This seems to mirror the more technically advanced theme of the book, as the user is required to know precisely where specific features are located in order to engage with the textual instructions. For instance, when explaining to the users the different functions of the brush tool, the book features a representation of the function, as seen in Fig. 1 below: Fig. 1 Brush Tool While the graphic representation is effective in accompanying the text, it lacks the ease of use of the Flash manual, which includes step-by-step visual representations of where to locate the specialized function. It’s possible this can be attributed to the increased complexity of Photoshop, with the need to incorporate a larger number of instructional lessons restricting the practicality of including full screen shots within the manual; it may also be attributed to the interactivity of the manual and CD lesson that accompanies it. However, in either instance, it reduces the overall effectiveness of the book as an instrument unto itself. Microsoft Word In Diane Koers’ Microsoft Word 2003 (2003) one sees an effective hybrid incorporation of the technical writing styles seen in the previous two examples. In the Mayfield Handbook of Technical & Scientific Writing, MIT Professor Leslie C. Perelman (1997, p. 10) writes that technical writing, “Good technical communication is accurate, clear, concise, coherent, and appropriate.” This style is exemplified greatly in Koers’ Microsoft Word manual. The Microsoft Word manual eschews the austere tone of the Photoshop manual while still effectively and efficiently communicating its instructions. When explaining the use of ‘Personalized Menus’, the manual begins its instructions with a large bold and italicized Sub-Heading. In the previous examples, these large subheadings were restricted to the beginnings of chapters, with smaller and denser dividers following them. The Microsoft manual then continues with an explanatory paragraph introduces the reader with a topic sentence that describes the function of personalized menus, “Word displays personalized menus which displays the features you use most often at the top of the menu (2003, p. 8).” The language follows Perelman’s advice for writing style in that it is clear and concise, without burdening the reader with unnecessary technical jargon. The paragraph continues further explaining the features of the personalized menus, “As you first access a menu, only the most common features are displayed. Notice the drop-down double pointing arrow at the bottom of the menu.” Again Koers’ uses coherent and appropriate language when explaining the features of the personalized menu. The text goes on to elucidate individual features of these menus and is followed by a numbered, step-by-step instruction of how to follow the process that was described in the paragraph above it. This approach targets opposing learning styles as it allows the reader to first read, process, and imagine the task at-hand, and then to see the task explained in more objective, step-by-step terms. This dual means of explaining the process, along with Koers’ concise and appropriate language, makes her technical instructions extremely effective. She is also greatly effective in anticipating the reader’s difficulties and preemptively offering solutions. Throughout the manual there is a section for tips that further illustrate user difficulties. Koers’ technical descriptions also make effective reference to miscellaneous issues users might encounter, “Most people find the Standard and Formatting toolbars difficult to use when displayed side-by-side, so you many want to separate them so one is on top of the other (2003, p. 12).” As has been discussed above, the successful incorporation of accompanying graphic descriptions is indispensable for effective technical communication. Koers’ Microsoft Word manual follows this knowledge perhaps more effectively than either the Photoshop or Flash manuals. Accompanying Koers’ descriptive and numbered, step-by-step instructions are full screen shots of the process being described. The textual description is flush left of the picture which makes it easy for the reader to glance between the two. This can be contrasted with the examples in the Flash manual, which contained full-screen shots, but were featured below the textual description and caused the reader to sometimes lose focus of what was previously discussed. It’s also more effective than the Photoshop manual as it allows the reader to seen the entire screen and not have to spend time search their computer before engaging with specific instructional functions. Conclusion In conclusion, the above referenced technical manuals effectively engage and aid the reader in varying ways. While the Flash manual makes excellent use of hierarchical structure and colloquialisms, it lacks sufficient user interactivity to reach its full potential. The Photoshop manual includes an accompanying CD, but may rely too heavily on terminology to be effective for the very novice user. Finally, the Microsoft Word manual makes excellent use of graphic and textual description to create a highly functioning instructional book. References Adobe. Adobe Photoshop 7.0 User Guide. New York: Adobe Press, 2002. Alred, Gerald. Handbook of Technical Writing. Boston: Instructional Publishing, 2005. Barker, Thomas. Writing Software Documentation: A Task Oriented Approach. New York: Stevens, 2001. Cooper, Elizabeth. Technical Writing Guide. London: Green Dot Publishing, 1998. Hargis, Gretchen. Developing Quality Technical Communication. California: IBM Press, 2004. Hestal, David. Principals of Technical Communication and Design. London: Dove, 2008. Koers, Diane. Microsoft Word 2003. New York: Course Technology, 2003. Perelman, Leslie. The Mayfield Handbook of Technical and Scientific Writing. Chicago: McGraw Hill, 1997. Vander, Emily. Flash 8: The Missing Manual. Boston: O’Reilly Media, 2006. Read More