Ragged Left

The newsletter for the Berkeley Chapter of the Society for Technical Communication

Editor's Notes

Submission Deadlines

The regular schedule is to post the PDF the first week of every even-numbered month (it's a bi-monthly newsletter), so I need content the last week of January, March, May, July, September, and November to publish the first week of February, April, June, August, October, and December.

Please include with your article a bit about yourself for the "author blurb" at the end of each piece.

President's Notes

The last couple of years have been hard. For those of us who are looking for work and can't find it, the situation still looks grim. Many signs, however, suggest an upturn. Our local job lists are no longer dormant, and people come to STC meetings with jobs to offer.

STC reports that the steep decline in membership has ended. The numbers are beginning to creep upward. After two years of annual conference losses, the Summit in Dallas returned a surplus. STC has cut expenses substantially and increased income. We appear to be on a firmer financial footing.

The Berkeley Chapter returned $6,000.00 in excess funds to STC last year, so our reserves are low. We have cut some expenses and are looking for ways to cut others. The Touchstone competition provides us a modest stipend each year, and we are looking for other income to help us continue to keep our meeting prices low. What our chapter needs above all else is your involvement. A few volunteers keep us going, but we have a hard time responding to the opportunities that arise. For example, we could reduce our expenses by changing the way we accept payments online, but none of our volunteers has the time and expertise to take on that project.

Our meetings are best when enough people attend. We have better networking and can attract better speakers with 35 people than we can with 15. Good attendance also helps us cover our fixed costs more easily.

So please come to a meeting, enjoy the networking and the presentation, and talk with me or any of our other regulars about how you can be more involved.

Developing and Delivering Documentation in a Wiki

Only a few years ago, many thought that Wikis would be the solution to all our technical communication problems. While there are definite advantages to Wikis, the reality of development, conversion, and maintenance issues have tempered the overly high expectations. Using a Gartner chart of the "Hype Cycle of Emerging Technologies," Dee Elling showed the audience at the April STC-Berkeley chapter meeting how Wikis have moved past both the "peak of inflated expectations" and the "trough of disillusionment" into the "slope of enlightenment" phase. More realistic views of Wikis and more experience with their development should move them into mainstream adoption within 2-5 years.

In her discussion of trends in technical communications, Dee noted that we are moving towards more two-way communication with customers who are becoming active participants in developing our knowledge base. "Many brains equal better information," Dee affirmed, and observed that the "lecture becomes a conversation." People are social learners, learning better together both in person and online, and Wikis facilitate that learning with interaction.

Embarcadero Technologies recently went through a transition from XML/DITA and MS Help2 to using MediaWiki to write and publish content. Before the transition, they were working with legacy technology, parts of which were over 20 years old. Documentation had been written using a variety of tools that only tech writers could (or would) use. A large and tangled API, and nearly 65,000 files in four different languages added to the complexity. In addition, the company had suffered a loss of knowledge due to layoffs. They needed a solution to manage the situation, and decided on MediaWiki.

Originally they had wanted to keep all content in XML, but in discussions about metadata and tags, they found that trying to standardize them was awkward and difficult. The Internet has changed the absolute need for TOC’s and indexes, as searches have become so advanced that the need for pre-defined tagging has become less important. It was a leap of faith for Embarcadero Technologies to give up XML and DITA, but after analyzing what they wanted to do and how MediaWiki could accomplish most of that for free, they made the leap.

MediaWiki gave them all of this except versioning. To work around this, they take "snapshots" now and then. Dee admits that this is not the best answer, but it is how they are dealing with it for now.

What MediaWiki gave them out-of-the-box was a CMS, revision tracking history, user management, and statistics. They added custom development items such as import/export scripts, CSS skins, user registration to enable editing, and the ability to rollback inappropriate or inaccurate changes.

The transition to Wiki also required new roles: Webmasters, Web Developers, and Web Monitors. Some existing roles went through changes as well. Writers and Editors had to learn wikimarkup and a new workflow. Document Architects and Planners had to become "WikiGardeners," repeatedly pruning and shaping the wiki pages as they grow and change.

Fortunately, there have been many positive experiences for the Wiki writers. Since wikitext is less structured than XML or FrameMaker, they find writing goes much faster. The development lifecycle also is quicker. Embarcadero Technologies is a distributed environment with employees in California and Rumania, and local writers are happy to be able to easily see the changes the Rumanian writers had made overnight. Another positive result is the enjoyment the writers have in building relationships with astute customers.

On the negative side, they have encountered some system problems (especially with slowness), and conversion issues (particularly with special characters, capitalizations, and international character sets).

Customer experiences also have both positive and negative elements. A better Help layout has been a real plus. On the down side, customers experienced problems with some links that were not working correctly in the beginning. In addition, there was resistance from some customers about having to register to make edits. Customer feedback came from only about 10% of their Beta account holders, but since they had done no real marketing, Dee said this is about what she expected. As for content input from the customers, Dee found that most was in the form of comments rather than direct changes.

Transitioning to Wiki entails certain "mind-leaps." One has to keep in mind that Wiki is always live --there is no downtime. Planning and institutional infrastructures are replaced by coordination and cooperative infrastructures. A personal connection with the customers becomes integral to the experience.

In conclusion, Dee spoke about lessons learned in hindsight. The biggest of these is that it takes more time and more experienced skills than they realized. They underestimated the technical complexity of the conversion. She also shared that they should have done more internal "marketing" to overcome the skepticism they encountered. Many people think that anything new just means more work for them, and unless they are given some incentives, it is difficult to motivate them. She suggested that showing them the advantages of moving the conversations from internal-only to internal and external would have helped to move the project along. Now that they are in the final phase of the transition, however, the positive aspects of moving to MediaWiki are apparent to all.

Dee Elling, Senior Writer and Senior Manager, Information Engineering at Embarcadero Technologies, is perpetually curious. She is always looking for new ways to meet the changing needs of web-centric customers. She is interested in lean development, rapid iteration, customer engagement and collaboration, and in growing self-motivated and technically-savvy teams.

Dee let the pioneering team at BEA WebLogic in bringing high-quality and highly relevant technical documentation to the Internet. WebLogic writers applied an automated continuous-improvement update cycle to what used to be static information.

Dee raised quite a few eyebrows by insisting that a writer’s first duty was to the customer who just found an issue in a "released" document, and that the writer should and could update that documentation right away. She also pushed the writers to prioritize examples as their most-effective deliverable.

As a result of this focus on quality, the WebLogic documentation website became a go-to site for Java developers, and was copied and emulated by other companies.

Dedicated to bringing the customer even closer to the content, Dee is now deploying Wiki solutions throughout the technical information development cycle at Embarcadero Technologies.

Jana Rollo-Fennick has over 10 years of Technical and Business Writing experience as part of the Pharmacy Systems IT team at Longs Drugstores Corporate Office. Recently, Longs was bought by another company and all the Corporate Office jobs were eliminated, so she is actively seeking work elsewhere as a Technical or Business Writer. She has developed a variety of documentation for multiple audiences, and is trained in Information Mapping concepts and formats. She is also a community volunteer and a trained Disaster Service Worker with CORE (Communities of Oakland Respond to Emergencies). For more information about Jana, please visit her VisualCV website, http://www.visualcv.com/hdjohkp.

Writing Effectively When Reading Isn’t Easy: Strategies and Ideas from the CH1 Workshop

When she started talking about FarmVille, she had me hooked. That anyone else would be interested in analyzing this social media game was appealing to me. FarmVille is not just my guilty pleasure, but I’m also studying reinforcement schedules, human interaction, compliance, incentives, reinforcement, and persuasive psychology! What makes things attractive and easy to use, and what makes reading attractive and easy to do is where Kath Straub, from Usability.org, brings her scientific knowledge of usability to technical writing and web design. We might be well-advised to take notes from advertising and psychological studies to "sell" our writing to our audiences.

Kath had recently attended the above workshop at the ACM Conference on Human Factors in Computing Systems held in Augusta, Georgia. If you want to see an excellent example of some of what Kath was talking about in regards to attractive, effective web design elements, check out their web site: http://www.chi2010.org/. There’s a good example of real-looking people "talking" to their audiences with the "call to action" of hear more... (too bad the links didn’t actually work, but you get the idea).

Her energetic presentation included some fascinating details and stories about research and development in the field of Usability. Understanding the blocks and barriers to reading and learning in order to find ways around them is the ultimate problem for writers who want to be understood. See Kath's slide presentation to see a complete list of reading "barriers." Barriers can be moved aside if the writing is good.

She emphasized the "gated-guided path." For this to work, you must know the needs of the audience for which you are writing. Then answer the important questions first.

Get them interested and then lead them gently into more detailed and complex topics.

Always talk about what’s relevant to the reader. Know what the reader needs, and what they have trouble with. This is especially important for documentation and training.

In the end, it's all about the reader, isn't it? Tell them why. Do things in order.

Use the right emotional "hooks" -- and fear is a most important hook. She asks questions two or three times to get to the emotional level for an effective hook. What could be our user's emotional needs? "I’m too stupid to learn this stuff." "I’m too old to learn a new program on the computer." "If I can't learn this quickly I'll be replaced."

Could this be why the "...for Dummies" series is so popular? f course, a little humor also helps.

She asked us in what kind of situations do we encounter difficult reading. Of course the physical presentation as to size and style of font, amount of white space on the page, a "ragged right edge" needs to be considered. Blocks of texts look good, but are hard to read. We have known these things for a long time. But now we are getting into different presentations; different media. She is seeing the new problem of changing media... from hard copy, to web display, to various electronic displays (think Kindle, think iPad) and now even to phone screen display. In the future, we may be writing for any number of new media. Other difficult reading situations are when we have deadlines, for example preparing our our taxes.

High-end readers tend to scan difficult text to move through quickly to get to the important parts. High-end readers may also scan because of boredom (it was pointed out that bad presentation also leads to boredom). Taxes present a triple problem of being difficult to understand, having a deadline, and being boring. Designing new, easy-to-read tax forms may be a new career for some enterprising writers (if they could keep their sanity).

Kath has analyzed reading on an extremely detailed level. Using different spacing between phrases, clauses, words, between consonants and vowels, and even between morphemes helps convey meaning to the reader, especially for the low reader and second language learners. For our purposes, she recommends being conscious of the phrasing in our documents. Line-endings need to correspond to phrase breaks using a "ragged right" for people reading under pressure (...reading the user manual), and for poorer, or even average readers in the population. She quoted studies of increased response of 114% on a website when this one idea was implemented. Direct mail comes back with an increase of 20% when the only change is the text breaks.

She stressed that even content has to be a conversation; needs to feel as if it's a two-way conversation; especially on web sites, although harder to do in User Manuals.

We are moving away from the "brochure" type website to something more interactive.

consumers want to interact, with a personal connection. They want a relationship, even with a website. Kath recommends introducing "small-talk" as part of the conversation.

Get your audience to navigate where you want them to go with a "call to action." Kath is passionate about how to get a person interested, how to seduce them, how to reinforce them, how to lead a person down the path. As for User Manuals, "they never read it ...unless they are in trouble." Maybe if we all spent more time collecting and analyzing data from the end-users, and using some of these techniques, the User Manual wouldn't be a choice of last resort.

Sherry Ashley has over 9 years experience in technical writing and web design for Longs Drugs in Supply Chain. When CVS purchased Longs, the corporate office was eliminated, therefore Sherry is actively seeking work in the technical writing field. She is currently updating and developing new skills in writing, learning new tools, creating Joomla! web sites, and doing public speaking at Toastmasters. For more information about Sherry see www.linkedin.com/in/sherryashley.

Editor's note: Sherry considered creating hard-breaks at the end of phrases (as Kath recommends) but our website adjusts column width.

Sell yourself: Listen, talk, communicate

How to Say IT® to Sell It covers the basics of selling yourself. The book begins with a section on listening.

Listening

"Most of the successful people I've known are the ones who do more listening than talking." – Bernard M. Baruch

While talking, such as, making presentations at Toast Masters, may be something we practice, listening is not. Sue Hershkowitz-Coore states: "Listening to your customer may be the hardest skill to master because sales people like to talk."

She goes on to discuss two reasons to listen: 1) Listen for points of agreement, and 2) listen for their (the customers) hidden questions.

A "point of agreement" is where you can meet your customer eye-to-eye. If your customer wants a presentation and you want to create a help system, you are not in agreement. To get into agreement with your customer, Hershkowitz-Coore states: "You only need to ask yourself: How can I help him 'be right?'"

If you can create a presentation, the project is yours. Or, as Tom Cum, a black belt in the martial art of aikado, says in the book: "Would you rather be happy or right?"

The "hidden question" is what the customer is really asking. Hershkowitz-Coore provides an example: You are selling your wares (whatever they may be) and the customer says, "That really won't work here." Before replying, ask yourself: "What is she really asking? The underlying question is: How can it work here? If you respond to the "hidden question", you may have a deal (or at least extend the sales conversation)."

From listening, Hershkowitz-Coore moves on to talking. She discusses what to say and how to say it.

Talking

A major point is to keep the sales conversation moving forward. Anything you say that contradicts the customer may end the conversation. Hershkowitz-Coore lists the following words as stoppers:

She goes on to provide alternatives for these words (and phrases). "Replace 'but' with 'and' and both parts of the sentence will have equal positive value."

Communicating

A major theme of the book is that all sales must center on the needs of the customer. Hershkowitz-Coore uses the adjective customer-centric (as in customer-centric communications, - dialogue) to name this theme.

"You never really understand a person until you consider things from his point of view... Until you climb inside of his skin and walk around in it." – Harper Lee, To Kill a Mockingbird

Hershkowitz-Coore provides ideas for understanding "your customer's motives for buying." "Listen. Customers tell you exactly what they'd like to buy from you. Don't discount what they have to say."

If your customer wants training, for example, don't show them procedures. Show them samples of exactly what they are looking for. (The book does say this may be hard if you have an exciting new product. If it doesn't fit the customer's needs, don't even bring it up.)

You now know exactly what your customer wants. It's your turn to keep the sales conversation going. Hershkowitz-Coore suggests that you "mirror their [your customers] communication patterns. If your customer prefers email, communicate through email. Be sure, though, to write email the way your customer would like to receive email."

A friend of mine almost lost a writing contract due to too many emails. The boss lamented, "He writes 10-20 a day." I asked, "What would you like?" She replied, "One email a day with all his questions/issues in it." I told my friend and the contract was saved.

Email is covered in a chapter called "Getting Your Email to Work for You." This chapter includes the following:

The Manners section includes one of my pet peeves: emails sent from Blackberries or iPhones. While there is a warning, something like "Sent from my Blackberry," I'm still frustrated by the emails. They are often cryptic and full of typos. Do I want to spend time deciphering them?

Hershkowitz-Coore describes an email she received with the disclaimer: "Sent from my Blackberry and not spell checked." She asked, "What is behind that message?" She goes on to ask, is it that "her time is too valuable to be bothered to spell-check "? This is not the message you want to convey to your customers. How can you change the message? Hershkowitz-Coore states: "Turn your Blackberry and iPhone's marketing message off." The customer does not care "whether you're communicating from a laptop, a personal device or iPhone." And, finally, she states: "stick to standards of proper business communication."

Conclusion

What makes this book work is that Sue Hershkowitz-Coore (http://www.speakersue.com/) is an internationally recognized sales trainer and speaker. Her writing style is short, clear and direct. In 210 pages, she covers everything you need to do to sell yourself. The learning is in the doing.

I suggest you read the book through and keep it nearby for reference. In the last paragraph, Hershkowitz-Coore concurs with me: "Keep it in your backpack or briefcase and reread the sections you know will help you drive sales, build relationships, and increase revenue."

Melody Brumis is a Senior Member of the Society for Technical Communication (STC). She has recently started a small business, Write on Time Solutions. Her column, Write on Time: Small Business Success, appears in the East Bay STC Chapter's Devil Mountain View. If you have comments on this book review, please write Melody at mbrumis@writeontimesolutions.com.

Meetings

Our chapter holds a dinner meeting the second Wednesday of each month. In addition to listing upcoming meetings, this section includes:

Upcoming Meetings

Focus On the User and the Rest Follows: Developing Personas to Improve Your Content

Wednesday, July 14, 2010, 6-9:30pm

Program

Content about your company, products, and services is a critical resource for communicating with your customers. But in today’s market your customers have never been more diverse or demanding. How do you meet their individual user needs? Such tools as structured content, XML, DITA, Component Content Management, and Dynamic Publishing provide the capability to manage and target your content. Technology gives you efficiency, but it doesn’t tell you who needs what. Understanding the content needs of your customers gives you the capability to create added value through your content.

This interactive presentation with hands on exercises introduces you to the steps for developing personas and how using those personas can improve your product information and learning.

Speakers

Joan Lasselle is the founder and President of Lasselle-Ramsay, Inc. Since 1982 Lasselle-Ramsay has helped global 1000 companies to get control of their new product or service content and deliver superior customer experience through content infrastructures. Lasselle-Ramsay has worked with industry leading companies such as Hewlett-Packard, Cisco Systems, Boston Scientific, and Fireman’s Fund Insurance Company. Joan is a senior member of STC, ISPI, a past board member of CMPros, and a regular contributor at industry conferences.

Jana Humphreys works with clients to design targeted learning and content solutions. Since 1992 she has worked on hundreds of curriculum design, custom training development, and technical documentation projects for a variety of organizations in the banking, finance, insurance, biotech, medical device, high-tech, and retail industries. Jana earned a Master's degree in Education/Instructional Technology from San Jose State University and is a past board member for the Silicon Valley Chapter of ISPI.

Meeting/Dinner Prices

Advance Reservations

Meeting and dinner

Program only

At the door (no reservation)

Meeting and dinner

Note: If you do not reserve dinner in advance, dinner may or may not be available on a walk-in basis. We order dinner for the number of reservations plus a few walk-ins.

Program only

Special cost notes

Meeting Agenda

6:00-7:00pm	Check-in, networking, conversation, and dinner.
7:00 -7:15pm	Chapter business, announcements, and introductions. Anyone can announce jobs that they know about.*
7:15 - 8:30pm	Formal program. Usually we have a speaker or panel of speakers on a topic related to the business or technology of technical communication.
8:30 - 9pm	Conversation, offline questions for the speaker, follow-up on job announcements
9:00 - 9:15	Clear the room. Move conversations to the sidewalk.

* Attendees, please announce open positions, and bring job listings for distribution.

Recruiters are welcome to attend meetings, place literature on a designated table, and talk with attendees one-on-one during the informal parts of the meeting. We ask them not to announce specific jobs during the formal announcement period, but they are free to stand up and identify themselves.

Similarly, we ask anyone else with commercial announcements to confine themselves to calling attention to the availability of literature on the designated table.

Berkeley STC Meeting Location and Directions

Note: If you need a ride from BART, contact Richard Mateosian (President@stc-berkeley.org) at least one day prior to the meeting.

Other contacts

Membership

Insurance

Worldwide activities

Local activities

Subscriptions

Advertising rates

Submissions

Editor's Notes

Submission Deadlines

President's Notes

Developing and Delivering Documentation in a Wiki

Writing Effectively When Reading Isn’t Easy: Strategies and Ideas from the CH1 Workshop

Sell yourself: Listen, talk, communicate

Listening

Talking

Communicating

Conclusion

Meetings

Upcoming Meetings

Focus On the User and the Rest Follows: Developing Personas to Improve Your Content

Wednesday, July 14, 2010, 6-9:30pm

Program

Speakers

Meeting/Dinner Prices

Advance Reservations

Meeting and dinner

Program only

At the door (no reservation)

Meeting and dinner

Program only

Special cost notes

Meeting Agenda

Berkeley STC Meeting Location and Directions

In this issue

STC News

Chapter News

Leadership Positions Available

Other STC chapters in Northern California

Other Organizations