SIGDOC Newsletter
December 2007 :: Volume 8, Number 4
Features
- Practitioners & Academics, Asking the Same Questions
Shaun Slattery, of DePaul University in Chicago, and current Secretary and Treasurer of SIGDOC shares thoughts on theory and practice, academics and practitioners.
- SIGDOC Sessions: The First Person Plural
Katherine Pawlick, who is new to SIGDOC conferences, shares insight that was in part sparked by a particular session this year in El Paso.
- Creating Documentation in the Open
Jeff Gardiner from Sun Microsystems on OpenSource documentation.
-
What is Design of Communication? Part 2, From Steve Murphy
Steve Murphy provides the second part of a three part Newsletter contribution as he reflects on what exactly falls within the bounds of what is termed “Design of Communication,” from a visual and graphics design perspective.
As the ongoing dialogue continues, please share your thoughts, findings, references, and opinions, about What is Design of Communication.
Practitioners & Academics, Asking the Same Questions
Shaun Slattery
sslatte1@depaul.edu
I’ve recently come back to SIGDOC. You’ll have to excuse my absence – I’ve been locked away in an ivory tower. So let me explain how good it was to be in El Paso, back among like-minded people, this past October.
Academia can be an isolating experience. As a newly minted Ph.D., I’ve spent the last few years engaged (absorbed?) in the dissertation and job-hunt processes, both of which are known to produce an unhealthy isolation. But my study of the composing processes of technical writers and how they manage writing in complex information environments put me in touch with several members of SIGDOC. The 25th ACM International Conference on Design of Communication was a great chance to meet so many people whose research interests overlap my own.
What I appreciate most about SIGDOC is the shared problem space – pracitioners and academics (and several blends thereof) asking the same or similar questions. Or asking very different questions about the same topics. As I watched one excellent presentation after the next, I was impressed by how quickly each was taken up by the audience. As a musician, I’ve played to a dead crowd; as a teacher, I’ve had my share of reserved students; and as an academic, I’ve seen listless conference audiences. This is not SIGDOC. The questions and discussion following nearly every presentation were extremely engaging.
At larger, traditional academic conferences, I tend pick and choose a handful of presentations to attend over a few days. SIGDOC gives me more bang for my buck – a premium, since my travel budget just shrank. My copy of the proceedings is riddled with sticky tabs. I’ve tagged papers on multimodality, information salience, and in-game communication as possible readings for my classes and I’ve saved David Christensen and Ryan Moeller’s interactive game board for “Playing in Genre Fields” for use in my next undergraduate writing class.
Even presentations which fell outside my own areas of specialization helped inform my awareness of the parameters of the field. My new friend Periklis Georgiadis, a research assistant for the Institute of Computer Science Foundation for Research and Technology at Hellas, expressed concern that his presentation was too technical, given the more theoretical discussions of earlier panels. What I found especially helpful about Periklis’ presentation, however, was his demonstration of turning user preferences into symbolic queries. His presentation helped me understand the very difficult process of operationalizing multiple and interacting user preferences that allow for the kind of personalized curricula his research group envisioned.
I find this back and forth between theory and practice, so typical of SIGDOC conference talks, especially instructive. I find it immensely helpful when these folks share their questions about communication and design, their techniques and methodologies, and the results of what they witness as they study and/or participate in communication and design.
I even got motivated. These presentations have sparked thoughts that I hope will become my own contribution to next year’s conference. And Diana award winner Judy Ramey’s lunchtime presentation of the work of University of Washington’s Laboratory for Usability Testing and Evaluation was downright inspirational.
Finally, I’m excited about SIGDOC’s leadership. As the newly-elected Secretary/Treasurer (when I get involved in an organization, I get involved), I was especially pleased with Sunday’s board meeting. This is a very dedicated and capable group of individuals who were extremely welcoming to this newcomer. SIGDOC, I’m glad to be back.
Shaun Slattery
Director of New Media Studies
Assistant Professor, Department of Writing, Rhetoric, and Discourse
http://condor.depaul.edu/~sslatte1/
SIGDOC Secretary/Treasurer
back to top
SIGDOC Sessions: The First Person Plural
By Catherine Pawlick
Catherine.Pawlick@Sun.COM
A number of papers presented at the SIGDOC conference proved interesting. Chief among them for me was a paper by Q. Dong, entitled “Cross-Cultural Considerations in Instructional Documentation: Contrasting Chinese and US Home Heater Manuals.”
I work for Sun Microsystems, which obviously doesn’t build or sell home heaters, but the issues that Dong mentioned about cultural viewpoints relate to Sun’s global technical writing team. Among other points, she discussed how America’s cultural basis on equality is reflected in technical documentation, whereas in China, where hierarchies remain entrenched and one’s status reflects one's position on the social ladder, the technical documentation reflects that as well.
I live and work in St. Petersburg, Russia. The longstanding argument over whether Russia is a European or Asian country remains. I would argue it is both at once, but in certain areas it is far more Asian than European. Scheduling and timing are categories that reflect the Asian outlook, without a doubt. The prominence of the group over the individual is also an Asian phenomenon strongly entrenched in Russia and one that America does not share. Russian resumes do not list what the individual did, but what the team on which they participated did – the verb form used is the first person plural, "we". Many tutorials and articles written by native Russian speakers reflect this viewpoint as well. I repeatedly correct “We will now build …”, changing it to the approved Western point of view, “You can…”. Westerners speak to the individual, not the group. Likewise, I have yet to be in a group meeting where any Russian will speak out against a policy.
Brainstorming is hard to do in Russia as well. Perhaps it hails from the days of Communism, or perhaps it is more of the collective mindset: if no one disagrees, then everyone agrees, we’re all in this together. In Russian, if I went to the movies with a girlfriend, the grammatical construction for that would be, “We with Amy went to the movies”; and not “I went to the movies with Amy”; also not “Amy and I went to the movies.” The phenomenon of the first personal plural predominates in Russia, and is reflected in words, both written and spoken.
This affects translatability issues, obviously. Should the Russian version of a Sun manual use the second person singular pronoun, since Sun is an American company? Or should it speak to the locals in their own style, incorporating the third person pronoun? Can Java tutorials in Russian keep the ubiquitous “we” when speaking to the reader?
In a larger sense, the use of the first person pronoun, when understood, provides insights into the speaker (or writer)'s intentions. Someone offering a suggestion will say, "Why don't we". But what they mean is "why don't you." It's a delicate difference but one that can have larger repercussions if misinterpreted.
In sum, when working with nonnative English speaking writers, a key to effective communication is understanding the cultural roots of the writer himself, for culture and language are inexplicably intertwined. This theme was revisited in many of the papers presented at the 2007 annual SIGDOC conference, a conference I was proud to be part of, and one that promotes cross cultural communication --and documentation-- on many levels.
Catherine Pawlick
Technical Editor, Sun Microsystems
St. Petersburg, Russia
back to top
Creating Documentation in the Open
Jeff Gardiner
Jeffrey.Gardiner@Sun.COM
Sun Microsystems open source projects like OpenSolaris provide the opportunity for creating documentation in collaboration with users. With a mix of hope and promise and the anticipation of many benefits, members of our teams have discussed and promoted this approach.
What better way to document a solution to a problem as it arises than to have an engineer engaged in the open source community write a How-To about it, or to have members write How Tos to solve unique problems that the author of a traditional document had not yet encountered or anticipated?
The practical benefits of co-authoring a document or submitting content, document fixes, reviews, and so on are attractive in principle. However, as with any project involving groups of people, the reality of collective development is complex. Motivating community members to write documents for an open source product, especially one with a full set of documentation from the proprietary product that spawned it, is difficult. If the existing documentation is comprehensive, the effort of conceiving, let alone writing, something new can be a barrier.
Over the past year, the number of bugs (text errors), patches, and reviews submitted by community members has remained level, with a few notable exceptions. For instance, patches and reviews submitted to the OpenOffice project increased dramatically in October 2007 when selected documents were made available in a wiki. That spike might indicate that many of our open source projects have yet to find the right mix of:
- Control vs. collaboration
- Complex structure vs. simple structure (which is easier to author and contribute)
- Adherence to familiar tools and processes vs. openness to varied approaches and (often less robust) tools
Still, the promise of collaboration is intriguing and many paths have yet to be explored. For instance, technical writing students, in particular students with a high degree of technical knowledge, are uniquely positioned to benefit from open source documentation projects.
These projects offer opportunities to develop a writing portfolio based on "real-world" information needs. Filling an information gap or enhancing an existing document set with additional How-Tos or troubleshooting tips is the kind of writing that lends itself to a class assignment.
Fundamentally, the deeper challenge seems to be whether open source collaboration can realize the kind of "relationship advocacy" proposed by Shoshana Zuboff. (I am indebted to Judith Ramey for drawing my attention to her work during a conversation at the 2007 SIGDOC conference.)
Can open source collaboration succeed in bringing users and developers (with multi-faceted and ever-changing information needs) into an ongoing creative relationship with corporate writers who have been traditionally the sole creators of technical documents? Can the development of information become an interaction that creates and sustains mutually informing relationships as well as documents? Would failing to meet this deeper challenge mean remaining stuck in the old transactional economy that Zuboff critiques (an economy in which, from a user documentation standpoint, the individual has been turned into a standardized consumer of information)?
As Sun's open source projects develop, we will see how creating documents in the open changes the form and processes of writing documentation and alters the relationship between the developer and user of information.
[Footnote: Shoshana Zuboff and James Maxmin, The Support Economy: Why Corporations Are Failing Individuals and the Next Episode of Capitalism (New York: Penguin Books, 2002).]
back to top
What is Design of Communication? Part 2, From Steve Murphy
by Steve Murphy
srmurphy@ca.ibm.com
Steve joined the SIGDOC community in 2002 to get better insight of industry practices that I could apply to my position as a graphic designer at the IBM Toronto Software Laboratory. He started at IBM as a production graphic designer creating various images that were needed for software products, including: icons, diagrams, packaging components, and illustrations, and is now an Information Development (ID) specialist. His stated objective for this three part Newsletter contribution is to achieve a broader definition of a graphic designer's role in the design of communication paradigm.
In part 1 Defining and improving graphic design services for information development (ID) deliverables, I described the business need for the Media Design Studio (MDS) ID deliverables production team to "clean house" which resulted increased efficiencies in the creation of various graphics. Thanks to a graphics request database, a file directory structure for storing images, and a checklist for quality assurance, the team and delivered output files satisfied clients along with the reducing the average turnaround time and overhead cost of creating graphics. Unfortunately during that period, there was little time for exploration in bettering graphic's usability.
Part 2 begins the journey in improving the quality of images through good graphic design practices.
As mentioned in part 1, the first 2 years' use of the MDS ID graphics request database brought a wealth of qualitative and quantitative information. We accumulated data to notice the following trends during the 2 year time span:
- Writers often inquired about screen captures (how to use them in documentation, which tool, which resolution, and so on)
- What MDS services were available to ID
- Problems MDS encountered when deciphering the content of clients' sketches
- Problems with certain types of graphics that consumed large amounts of time for graphic designers to reproduce
How can MDS resolve these issues? The phenomenon was not localized to one ID group. The same problems were reoccurring in other teams, but not always prioritized or brought to MDS's attention. The approach was multipronged: meeting one-to-one (one ID team and MDS team lead) for discussions, allying with the Toronto ID editing department as a joint venture, or creating best practices. Being receptive to the ID teams graphics dilemma provided MDS an opportunity to work more closely with writer forging a new relationship. A chronic problem with using screen captures brought the first of the ID and MDS co-authored best practices. The screen capturing guidelines was well received and to this day is still in use 8 years after its inception.
Seeing the success of the screen capturing guidelines in use at the Toronto Lab, MDS reflected on extending this idea of guidelines to other types of graphics such as concept and syntax diagrams. Workgroups were formed with writers, editors, and graphic design resulting in guidelines that conformed to IBM in-house writing styles and graphic design practices. The partnership changed ID's perception of MDS services from production designers to communication collaborators.
The other objective of guidelines was to provide stylistic guides to graphic designers who were creating the ID graphics. These styles were the beginning of the end for individual expression which is unfortunate for artistic creativity, but highly praised when addressing the holistic improvement of concept diagrams' usability. Part of the styles guidelines included:
- A library of commonly used clip-art objects (for example, server, workstation, HTML file, and so on)
- A library of reusable shapes
- A custom color palette for shapes and other graphical elements
- Fonts and font attribute references
- Other graphical elements such as arrows and lines
- Step-by-step instructions for constructing diagrams
Over time, the revision of Toronto ID teams' concept diagram libraries created an improved consistency and increased usability of old black and white images ( see figure 1 and 2).
Figure 1: A before example of a black and white concept diagram
Figure 2: An after example of a black and white concept diagram recreated in color and with improved usability
UML diagrams also needed our attention. Models of class, sequence, and use case diagrams were flooding the request database. Some were intimidating in their size and content (see figure 3). A desire to solve this issue urged the formation of the Toronto Lab UML diagram workgroup. Another set of guidelines was developed based on a process that instructs the creator of UML diagrams how to optimize the software design stage models for repurposing in user assistance documentation. These best practices were published in SIGDOC conference proceedings:
- Designing UML Diagrams for Technical Documentation, SIGDOC Conference Proceedings 2003, p. 105
- Designing UML Diagrams for Technical Documentation: Continuing the Collaborative Approach to Publishing Class Diagrams, SIGDOC Conference Proceedings 2004, p. 120.
- Sequence Diagram Presentation in Technical Documentation, SIGDOC Conference Proceedings 2004, p. 128
Figure 3: An example of a UML class diagram that is out of control!
Now, the best practices are published and in use. Writers continuously consult the documentation to help them in making decision or properly sketches of MDS. Everyone is happy. Well, the world is a changing place and IBM documentation is no different! Cross-site software product development was gaining in popularity because IBM was now promoting software solutions to businesses in the form of bundled software packages. Documentation followed suit. Toronto ID writers collaborated with colleagues from around the world providing topic-based technical information to customers.
In part 1, I mentioned that the graphics for Toronto Lab information development team was inconsistent. Though that problem was resolved by the creation of best practices, MDS was challenged once again with diagrams created by graphic designers from other Labs that did not conform with our in-house styles. With the cross-site software development mentality being the new norm, inconsistency reared its ugly head again for concept diagrams. It was time to move the best practices from a local style to a corporate, IBM worldwide one. Working with MDS management, we pitched our best practices to the IBM ID advisory counsel. Coincidently, graphic designers from IBM Systems group were presenting a parallel proposal. Merging the 2 proposals and teams together made sense and gave birth to the non-text information (NTI) workgroup as named by the ID counsel. The fruits of the NTI workgroup is one of topics for part 3: Corporate styles and innovation--the building blocks for the future of information development graphics.
In summary, part 2 continues the momentum of bringing efficiencies to the design of graphics. With issues abounding, ID editors, writers and graphic designers collaborated to co-authored the first guidelines for screen captures establishing a partnership to resolving design challenges in both textual and graphical information. Quick to follow were more guidelines, but this time these graphic design methodologies were for the clean and succinct presentation of concept, syntax, and UML diagrams.
It is not by chance that the user experience for diagrams and screen captures improved. When members of both disciplines (writing and graphic design) understand each others skills in communication, the results is a more harmonious and persuasive solution for documentation.
Coming up next, part 3 will describe broadening the scope of the written medium while taking a step away from the traditional presentation.
Cheers,
Steve
Steve Murphy
Illustrator/Media designer
Markham, Ontario
back to top |
