Webcast: Managing technical communicators in an XML environment
In this 41-minute webcast, Sarah explores how XML affects the management of technical communication and proposes a new system for measuring documentation quality.
Author: Sarah O'Keefe
Managing technical communicators in an XML environment
To understand how XML changes technical communication, we need to step back and look at how the rise of information technology has changed the content development process. Through the 1970s, most technical communication work had separate writing, layout, and production phases. Authors wrote content, typically in longhand or on typewriters. Typesetters would then rekey the information to transfer it into the publishing system. The dedicated typesetting system would produce camera-ready copy, which was then mechanically reproduced on a printing press.
In a desktop publishing environment, authors could type information directly into a page layout program and set up the document design. This eliminated the inefficient process of re-entering information, and it often shifted the responsibility for document design to technical communicators.
The Tech Comm Manifesto
My life in technical communication would be much easier if we all subscribed to these rules:
Trends in technical communication webcast
After some “interesting” technical challenges, the recording of our Trends in technical communication webcast is now available on Slideshare:
Webcast: Trends in technical communication for 2010
Sarah O’Keefe, Ellis Pratt of Cherryleaf, and Tony Self of Hyperwrite
Find out where these three presenters see the industry going. This event is for managers with tech comm responsibility, with or without prior technical writing experience.
The state of structure in technical communication
In early 2009, Scriptorium Publishing conducted a survey to measure how and why technical communicators are adopting structured authoring.
But will it blend?
In choral music, “blend” refers to bringing together a diverse group of voices into a pleasing sound in which no single voice is dominant. As technical communication moves into a more collaborative approach to content, it occurs to me that both writers and musicians need to blend. Here are some choral archetypes and their writerly equivalents:
- Soloists—singers with big, powerful voices or writers with distinctive styles—are a challenge to blend. The singers must reduce their volume to match the voices around them and sing the music without adding ornamentation. Writers must refrain from their favorite distracting rhetorical flourishes.
- Section anchors—journeyman singers who know their parts cold and provide support to others singing the same part. Section anchors may not have the vocal quality of a soloist, but they are competent singers who are always on pitch, learn the music quickly, and follow the director. On the writing side, this is a person who writes competently, knows the product being documented, always follows the style guide, and learns quickly. In a writing group, these may be the team leaders. They are not necessarily the flashiest or the most gifted writers, but their content ranges from acceptable to excellent.
- Supporting players—these singers lack confidence, but can learn their part and sing it, provided that they have support from a section anchor. Left to their own devices, they may drift off into another part (usually abandoning harmony to sing the melody line). But as long as someone nearby is singing their part with them, they can stay on pitch and contribute their voices. This equates to writers, often with less experience, who need support, encouragement, and editing to stay within the style guide. They need help in most aspects of the content creation process. Over time, supporting players can improve and grow into more confident section anchors both in writing and in singing.
- Blissfully tone deaf—Fortunately, many people who are tone deaf (or simply cannot write) are aware of their limitation. But if you’ve spent any time at all in a volunteer choir, you’ve probably experienced people who make up for their lack of pitch by singing louder. In a writing context, your best bet for the tone-deaf (short of a new job!) is to give them assignments that minimize actual writing, such as creating basic reference information (not a lot of room to maneuver).
Our challenge, as writers, is that we have been accustomed to working solo, and now we must learn to blend our authorial voice into the larger group. The skills that make great soloists are not the same skills that make great contributors.
WritersUA: Wireframing tools and techniques
Michael Hughes, IBM ISS Security Systems
Yay, I finally get into a session.
Wireframes can be high fidelity (rendered dialog box that looks like the real thing) or low fidelity (sketch on a bar napkin). Fidelity actually has several components: appearance, medium, and interactivity.
Low fidelity appearance is something that looks (or is) hand drawn. High fidelity looks like a finished UI. Low fidelity appearance can be advantageous because people don’t get distracted.
Low fidelity medium is paper; high fidelity medium is an actual user interface.
Low fidelity interactivity is static—a picture of the thing. Then, you have scripted interactivity, where you take people through a scripted, controlled sequence. Next is intervention…the user says what they would do and then the UX designer shows them the next result. This can be done with paper prototypes. Finally, you have functional interactivity, where the various UI components actually work.
Low fidelity advantages: Quick, easier, and cheaper to create and modify. More importantly, people are more willing to give feedback on something that looks finished. People are afraid to give feedback on something that looks polished because they don’t want to hurt your feelings, but if you provide a low-fidelity wireframe, you will get much more candid feedback.
Low fidelity disadvantages: You might get detailed feedback on irrelevant details (“this button should be square and not rectangular”). Limited ability to watch users interact. Some users cannot visualize the final product from a low-fidelity version.
High fidelity advantages: The prototype is more realistic. Easier to understand and less room for misinterpretations. You can watch the users interact with the design.
Low fidelity disadvantages: More expensive to create, less encouraging of feedback, people focus on minutiae, easy for designers to become emotionally involved.
(“You might throw in lorem ipsum text and then have people correct your Latin.”)
As you move farther into development, fidelity generally needs to increase.
Higher fidelity is important when you have higher usability risks due to lots of interactivity, complex UI, new interactions and content (for dev team or users), where in user task flow does UI occur (earlier is riskier).
Tools & their best uses
Bar napkins: Good for early conceptual designs, not so good for felt tip pens and putting a wet beer glass on.
Paper prototypes: Can create the various interfaces and do some paper-based flow testing. Not so good for a sense of scale or for assessing content.
PowerPoint: Can do hyperlinks and action buttons. Create each interface on a slide and then link them with PP features. Use slide sorter and rearrange to simulate various user workflows. For web design, put a browser window on the slide master to force you to stay in the browser space. Good for sense of physical navigation, planning layout, producing paper output, presenting look and feel for interactive web pages. Not so good for complex interactions and for look and feel of applications.
Visio: Pretty good set of widgets for making realistic-looking dialog boxes. Similar pluses and minuses as PowerPoint, but also good for look and feel of applications. Can use to incorporate wireframes with flowcharts, use case diagrams, and other macro-design tools.
Balsamiq Mockup: Presenter’s favorite tool (mine, too). Extended demo. If you’re interested, try it online for free. Realistic enough to help designer imagine what the user experience will be.
Pencil (Firefox plug-in): “they have the world’s worst online help”
Axure demo: Can build tooltips. Higher fidelity than Balsamiq. Lets you take note and annotate the fields and then print as a Word file. Use to lay out business rules, alternate text, and more. Suitable for Web 2.0 interactions, which are difficult or impossible in Visio.
Information as a right
Bear with me in a post that’s going to be even less coherent than usual. (And that’s on the heels of the Great Graphic Debacle.)
Is access to information a right or a privilege?
In democracies, we believe that citizens have a right to their government’s information.
U.S. citizens are likely familiar with the Freedom of Information Act (FoIA) and the various sunshine and open meeting laws. In 2005, India passed a Right to Information Act, which “requires every public authority to computerise their records for wide dissemination and to proactively publish certain categories of information so that the citizens need minimum recourse to request for information formally.” Other countries have similar legislation; the Right2Info organization “brings together information on the constitutional and legal framework for the right of access to information as well case law from more than 80 countries, organized and analyzed by topic.”
In the absence of a compelling government interest (the FoIA has nine, which include national security and personnel privacy issues), governmental information should be available to citizens. (This does assume, of course, that we are talking about governments who acknowledge that they are accountable to their citizens.)
If governments have an obligation to make information accessible to their citizens, does that equate to a right to the information? What about equal access to information? Is that a right?
For example, if certain public information information is readily available only on the Internet, does it follow that a citizen has a general right to Internet access? This question was actually considered by the European Union parliament last year, in the context of a new French law that cuts off Internet access to repeat offenders who infringe on copyrights with file-sharing:
Opponents of the legislation have responded by suggesting that Internet access is fundamental to liberty, an argument that suffered a setback on Wednesday as the European Parliament voted against codifying Internet access as a basic human right. (Is Internet Access a Fundamental Right?, CNet.com, May 6, 2009)
There are also interesting developments in financial information. The U.S. Securities and Exchange Commission (SEC) requires publicly traded companies to make certain information available to the public. This information is delivered through the EDGAR (Electronic Data Gathering, Analysis, and Retrieval) system.
Currently, the official submission format for EDGAR data is plain text or HTML, but the SEC is phasing in the use of an XML vocabulary called XBRL (Extensible Business Reporting Language).
“The purpose of the XBRL mandate is to make corporate financial information more easily available to stockholder.” (The XBRL mandate is here: Is IT ready?, Ephraim Schwarz, InfoWorld, November 25, 2008)
So in addition to mandating disclosure of corporate financial information, the SEC is now mandating easier access to the disclosed information. (A simple implication of XBRL is that you could more easily find executive compensation numbers.)
But what about non-governmental, non-regulated information? Is there a right to access? The business model of analyst firms (Gartner Group), business research companies (Dun & Bradstreet, Hoover’s), and, for that matter, the entire publishing industry (!!) says no. If you want information, you pay.
But look at the evolution of government philosophies and with that, content disclosure requirements. A king who reigns by divine right discloses what he wants to. A democratically elected leader must justify a lack of disclosure. It seems clear that we have shifted to the idea that access to government information is a right.
Will commercial information evolve in the same direction? There are actually some developments that point toward information as a right. In particular, the idea that information must be accessible—that information presentation should not exclude those with visual impairments or other disabilities—begins to build a foundation for equal access to information as a right.
What do you think? Will the right to information access be considered a bedrock principle in 50 or 100 years?
Sleepless in Seattle—our agenda at WritersUA
Simon Bate and I will be attending WritersUA this year.
I will be mainly camped in Scriptorium’s exhibit booth. Hours for that are Monday 8:00 am – 6:00 pm and Tuesday 8:00 am – 5:30 pm. Please stop by when you get a chance. Simon will be joining me, but is also presenting on XSL Techniques for XML-to-XML Transformations on Monday at 3:25. Here’s a bit of the description:
In a recent project, we used XSL to correct markup and fix conversion errors in 55,000 XML files containing 2000-year-old Greek texts. The clean-up work included correcting errors in the Greek numbering system, converting text-based markup to XML, replacing or repairing missing markup, and ensuring the accuracy of our work in such a large document set. This session uses this work to illustrate how XML-to-XML transforms differ from XML-to-output transforms. Along the way we describe some XSL techniques we created for processing XML data in which there is a close relationship between the content and the markup.
This year, we’re bringing swag in the form of free copies of The Compass, a printed compilation of Scriptorium white papers. For WritersUA, we have two new white papers, and the book is now almost 200 pages long. (Our white papers are also available, for free, in HTML and PDF format.)
If that’s not a sufficiently sweet enticement, you can also expect local chocolates. The leading contender is currently Fran’s, but I’m open to suggestions, especially from Seattle locals. (We generally pick up chocolate once we arrive rather than attempting to ship it. Ask me some about the Great Truffle Shipping Debacle.)
Simon and I are both scheduling private meetings during the event. If you are a current or prospective client of ours, or if you just want to talk, let us know and we’ll set something up.
