Skip to main content

Author: Sarah O'Keefe

Opinion

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.

Read More
Industry insights

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.

Read More
Opinion

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?

Read More
Industry insights

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.

Read More
Industry insights

Conferences versus social media

The information you can get from a conference presentation is usually available online—in blogs, webcasts, forums, and/or white papers. So why should you invest the time and the money to attend an event in person? In the end, there’s something very powerful about eating and drinking with a group of people. (And no, alcohol is not required, although it doesn’t hurt. Until the next day, when it hurts a lot.)

The value of conferences, which is not (yet) replicated online is in the “hallway track”—the discussions that happen between the formal sessions:

“[B]eing able to establish a one-to-one personal connection with other professionals in your field is critical to being a success.” (Dave Taylor in The Critical Business Value of Attending Conferences)


“I’ve found that time and again, I’ll hear speakers or audience members or participate in conversations and lie awake that night jam-packed with new ideas (some that don’t even correspond remotely to the concepts discussed that day). Conferences are a brainstorming paradise and a terrific opportunity for new ideas to come bubbling to the surface.” (Rand Fishkin, The Secret Value of Attending Conferences)

Scriptorium has quite a few social media “features”:

  • This blog, started in 2005
  • Webcasts, 2006 (recordings available for recent events)
  • Forums, this week (currently in the “awkward silence” phase. Help us out by posting, please!)
  • Twitter

But there’s something missing. I’ve attended and presented quite a few webcasts, and I can tell you that it’s actually far more difficult to deliver a compelling webcast than a compelling conference presentation. As the presenter, you lose the ability to gauge your audience’s body language. As an attendee, you have the temptation of your email and other distractions. The audio coming through your computer or phone is somehow not real—it’s easy to forget that there’s an actual person on the other end giving the presentation online. (There’s also the problem that many webcasts are sales pitches rather than useful presentations, but let’s leave that for another time.)

In my experience, it’s much easier to sustain online friendships with people that I have met in real life. Even a brief meeting at a conference means that I will remember a person as “that red-haired woman with the funky scarf” rather than as an email ID or Twitter handle. So, I think it’s important to go to conferences, meet lots of people, and then sustain those new professional relationships via social media.

In other words, conferences and social media complement each other. Over time, I think we’ll see them merge until a new interaction model. For example, we are already seeing Twitter as a real-time feedback engine at conference events. (Here’s an excellent discussion of how presenters should handle this.) Joe Welinske’s WritersUA is experimenting with a community site tied to the conference.

What are your thoughts? How important are conferences to your career?

Read More
News

Talk amongst yourselves…introducing forums.scriptorium.com

Our web site now has forums for discussions of technical communication issues. We want to give you, our readers, a venue where you can set your own agenda instead of just responding to our blog posts.

Given Scriptorium’s particular interests, I expect to see a lot of emphasis on publishing automation and XML. But frankly, we don’t know exactly what might happen. Communities often develop in unexpected ways. It will be up to you—and us—to figure out what direction these forums go.

(We have an internal pool on how long before Godwin’s law is applied.)

The forums are available in our main site navigation. There are also RSS feeds so you can subscribe to a topic or category of interest. Or, if you prefer, you can get email notifications for new forum posts.

And how do we feel about this launch? We’re…perfectly calm.

Please join the conversation.

Read More
Opinion

The elephant in the room—publishers and e-books

Two years ago, Nate Anderson wrote this on ars technica:

The book business, though far older than the recorded music business, is still lucky enough to have time on its side: no e-book reader currently offers a better reading experience than paper.

That’s what makes Apple’s iPad announcement so important. Books will now face stiff competition from e-books as the e-book experience improves.

Elephant in the room // flickr: mobilestreetlife

Elephant in the room // flickr: mobilestreetlife

Meanwhile, the publishing industry (with the notable exception of O’Reilly Media) is desperately trying to avoid the inevitable. (For a slighty happier take, see BusinessWeek.)

Publishers are supposed to filter, edit, produce, distribute, and market content. pre-Internet, all of these things were difficult and required significant financial resources. Today, many are easy and all are cheap.

There’s only one other thing.

Content.

But the revenue split between publishers and authors does not—yet—reflect the division of labor. The business relationships are still built on the idea that authors can’t exist without publishers. In fact, it’s the reverse that’s true.

Only the big publishers can get your book into every bookstore in the country. However, I’ve got news for you: Unless your name is on an elite shortlist with the likes of Dan Brown, John Grisham, Nora Roberts, and J.K. Rowling, it probably doesn’t matter.

If you know your audience, you can reach them at least as well as a big publisher can. And you need to reach a lot fewer people to succeed as an independent. The general rule of thumb is a 10-to-1 ratio. You’ll make the same amount selling 10,000 books through a traditional publisher as 1,000 books on your own.

It’s not so difficult to hire freelancers (especially in this economy) to edit and produce your book, if that’s not your cup of tea. Distribution is doable—Amazon is easy, bookstores a little more challenging. This is where e-books will accelerate the change—the challenges of shelf space and returns simply disappear.

And even if you have a publisher, they will expect you to do most of the marketing.

So, what will successful publishers look like in 2020?

  • They will provide editorial and production support for writers who do not want to deal with technical issues.
  • They will support authors in marketing by helping them with blogging platforms and other social media efforts.
  • They will get a much smaller cut of revenues than they currently do.

Actually, that looks a lot like Lulu.

    Read More
    Content strategy XML

    XML: The death of creativity in technical writing?

    Originally published in STC Intercom, February 2010.

    I spend a lot of time giving presentations on XML, structured authoring, and related technologies. The most common negative reaction, varied only in the level of hostility, is “Why are you stifling my creativity?”

    Does XML really mean the Death of Creativity for technical communicators? And does creativity even belong in technical content?

    Read More
    Opinion Webinar

    Behold, the power of free

    Lately, our webcasts are getting great participation. The December event had 100 people in attendance (the registered number was even higher), and the numbers for the next few months are strong, as well. Previous webcasts had attendance of A Lot Less than 100. What changed? The webcasts are now free. (Missing an event? Check our archives.)

    We’re going in a similar direction with white papers. We charge for some content, but we also offer a ton of free information.

    The idea is that free (and high-quality) information raises our profile and therefore later brings in new projects. I’m not so sure, though, that we have any evidence that supports this theory yet.

    So, I thought I’d ask my readers. Do you evaluate potential vendors based on offerings such as webcasts and white papers? Are there other, more important factors?

    PS Upcoming events, including several DITA webcasts, are listed on our events page.

    Read More
    Opinion

    2010 predictions for technical communication

    It’s time for my (apparently biennial) predictions post. For those of you keeping score at home, you can see the last round of predictions here. Executive summary: no clear leader for DITA editing, reuse analyzers, Web 2.0 integration, global business, Flash. In retrospect, I didn’t exactly stick my neck out on any of those. Let’s see if I can do better this year.

    Desktop authoring begins to fade

    Everyone else is talking about the cloud, but what about tech comm? Many content creation efforts will shift into the cloud and away from desktop applications and their monstrous footprints (I’m looking at you, Adobe). When your content lives in the cloud, you can edit from anywhere and be much less dependent on a specific computer loaded with specific applications.

    I expect to see much more content creation migrate into web applications, such as wiki software and blogging software. I do not, at this point, see much potential for the various “online word processors,” such as Buzzword or Zoho Writer, for tech comm. Creating documents longer than four or five pages in these environments is painful.

    In the ideal universe, I’d like to see more support for DITA and/or XML in these tools, but I’m not holding my breath for this in 2010.

    The ends justify the means

    From what we are seeing, the rate of XML adoption is steady or even accelerating. But the rationale for XML is shifting. In the past, the benefits of structured authoring—consistency, template enforcement, and content reuse—have been the primary drivers. But in several newer projects, XML is a means to an end rather than a goal—our customers want to extract information from databases, or transfer information between two otherwise incompatible applications. The project justifications reach beyond the issues of content quality and instead focus on integrating content from multiple information sources.

    Social-ism

    Is the hype about social media overblown? Actually, I don’t think so. I did a webcast (YouTube link) on this topic in December 2009. The short version: Technical communicators must now compete with information being generated by the user community. This requires greater transparency and better content.

    My prediction is that a strategy for integrating social media and official tech comm will be critical in 2010 and beyond.

    Collaboration

    The days of the hermit tech writer are numbered. Close collaboration with product experts, the user community, and others will become the norm. This requires tools that are accessible to non-specialists and that offer easy ways to manage input from collaborators.

    Language shifts

    There are a couple of interesting changes in language:

    • Content strategy rather than documentation plan
    • Decision engine (such as Hunch, Wolfram Alpha, and Aardvark) rather than search engine

    What are your predictions for 2010?

    Other interesting prediction posts:

    Read More