Monthly Archives: June 2008

Creating social media versus social networking

An interesting comparison and contrast with two recently added time-sink temptations while online.

As of a few weeks ago, you can submit news stories to the new, a digg clone site with the clever Sink or Float capability on news stories, built by Tom Johnson who writes the IdRatherBeWriting blog. A few months ago, Scott Abel, The Content Wrangler blogger, started, where you can build a profile for yourself and interact with other members via discussions and postings.

So, all technical writers, technical communicators, information designers and architects and other such content wranglers: which online activities do we prefer? Are we networking online or creating online media?

In the last six months or so, have seen shift in thinking towards social networking as a preferential term rather than the phrase social media. I think that this change in the terminology is a result of the constant comparisons of old media versus new media, such as comparing printed newspapers to online blogs. But, for a set of future thinkers, blogs and blogging feel like old news, especially to the leading web design people. So perhaps this crowd is the one preferring the term social networking. I know I heard social networking much more often than social media at SXSW Interactive 2008.

It’s interesting, though, in contrast, Danah Boyd points out in a November 2007 O’Reilly Network interview, “I don’t call them social networking sites because most users aren’t “networking” per say [sic]. They are modeling and maintaining their pre-existing social networks.”

So this rambling brings me to our two new social sites. In the case of, people who are perhaps not natural networkers won’t “get” the site right away.

For, I’m not sure if non-natural networkers will “get” the site right away either, but there’s also a little bit of journalist enthusiasm and “scooping” a story that will help you “get” the usefulness and entertainment out of the site.

For anyone who has read The Tipping Point, I ask this (and I’ve mentioned this to Gordon McLean so I hope he gives his take as well): are people who tend to be technical writers naturally Connectors or naturally Mavens?

Connectors are the people who “link us up with the world … people with a special gift for bringing the world together.”
Mavens are “information specialists”, or “people we rely upon to connect us with new information.”

With all this in mind, I offer my personal take on how I can use each site.

How I use If I like a story, and think it’s relevant to writers, I copy the URL, then go to and enter the URL along with a brief description of the story. Others can come read the story and my summary and “float” it further up the river. I check in on it every few days to gain new insights or see the freshest stories. I also see how far up river my submissions have gone, and check on any comments, especially from writers I know through online communications and in real life.

How I use TheContentWrangler.Ning site: I built a Profile page with my blog feed as content, then I started or joined groups that I think would give me connections to mind power that I wouldn’t already have through some of my other connections. I set notifications only to email me on specific discussions that I started or want to watch, and I pop by every week or so to see what’s going on with discussions, the blog entries on the front page, and other media.

Please, let me know if you find this helpful, or if you have suggestions for your own uses that are different from mine.


Check her out!

Here’s my interview for GirlStart, highlighting a technical communication career for the “Check her out!” section of their website. The toughest question for me was the last one! GirlStart is a non-profit based in Austin that empowers girls in math, science, and technology. I was pleased to be able to say what a great career information development is, and also reading the other interviews was an inspiration to me!
So, here goes.

Senior Technical Writer, blogger
Advanced Solutions International and

What do you do and what are some of your job responsibilities?

I write online help, website information, and user manuals for software that people use to run associations, non-profit organizations, and faith-based organizations. Our software can conquer mailings, large events, fundraising, organize and retrieve member contact information, and handle magazine subscriptions just to name a few tasks that large organizations do for their members.

I have to learn new features of a product quickly, and analyze the tasks that our typical users want to accomplish with our software product. Technical writers are sometimes described as extremely fast learners who can also interview to get the information they need as well as a journalist. My job involves writing, interviewing, learning about users, checking the software for quality, helping improve the user experience with the product, and constantly checking the future horizon to ensure our deliverables match what our customers want.

I also write a blog about information development and design at, and it has helped me learn so much and connect and collaborate with others in my chosen field. I started blogging for my former employer, BMC Software, and it opened doors and opportunity to me because it moved me to the edges of my comfort zones.

How did you find your current job?

I belong to a professional organization called the Society for Technical Communication, and networking through those affiliations has helped me find every single career-type job I’ve found so far. Professional networking and social networking are huge parts of job-hunting, especially for fulfilling, flexible work like the jobs I have found a passion for.

Did you learn any of your skills from school?

I’m a little unusual in that my path to technical writer started with an undergraduate degree in chemistry, where I learned a lot about scientific thinking and process. After reading the manuals in the analytic laboratory where I worked for a summer testing powder samples of infant formula, I decided to explore how those manuals were written. I discovered a master’s degree program in scientific and technical communication and learned a lot of my specific job and career skills there, but I have also had to continually educate myself and reach out to others to learn more skills, for both technical and design-oriented skills. I also read a lot – books or blogs, either one is highly useful and helpful to me. I attend presentations, conferences, and training classes as well.

What would you tell a girl that was interested in doing what you do?

Technical writing and information design are professions that a lot of women have found to be fulfilling and interesting, and for many reasons, women are prevalent in the profession. I’d encourage you to read as much as you can and practice writing because both are important skills for writing technical information. I also would encourage a sense of excitement and exploration with technology, whether it’s Webkins or a Nike+iPod running sensor.

What are some of your hobbies?

I enjoy running very much and while I’m not fast, I am consistent. I’m into running for the long term ever since I found the best running partner in a friend 30 years older than me. I also write for my blog as a hobby and explore the latest technology in social media and computers by talking to my friends and colleagues online. I read voraciously and have joined at least three book clubs in the last few years. I also enjoy kids and especially my own kids. I teach my son’s classes as often as they let me and love going on field trips, even if they’re just in the backyard with a flashlight or binoculars at night.

What is your favorite website?

My favorite website is because that’s where I store all my blog feeds to read, and reading is my absolute favorite pastime. Probably my favorite website to visit is because she’s an excellent writer and her daughter and my firstborn son are nearly the same age, so much of what she writes about I’m living. Right now, I enjoy because it’s where I’m bookmarking all my favorite places to read and savor later. To talk with friends and coworkers, I enjoy and

If you could talk to you when you were 12 years old, what advice would you give yourself?

This is a tough question, I have to say. Don’t argue with others for the sport of it comes to mind first, because my wise sixth grade teacher wrote that in my yearbook. Secondly, you’re not fat! Looks don’t matter as much as you think, but perceptions of presence, actions, and words (written and spoken) do matter. Learn as much as you can from those more experienced than you, and learn how to listen really, really well.

agile techpubs

Reading lists for technical writing

As a graduate student in scientific and technical communication, I was fortunate to have been introduced to many texts for learning technical writing at Miami University in Ohio. I have kept those books, keeping them on my bookshelf wherever I work, and have added to that bookshelf ever since. Perhaps this list could be considered the start of a “classics” list.

The Elements of Style (Coyote Canyon Press Classics) (Coyote Canyon Press Classics)
William Strunk
I agree with the New York Times’ assessment: “Buy it, study it, enjoy it. It’s as timeless as a book can be in our age of volubility.”

Technical Communication: A Reader-Centered Approach
Paul V. Anderson
I learned at Miami University from Paul V. Anderson, author of this book. I don’t have this latest version
but I’m sure it would be useful for both students and experienced practitioners.

Managing Your Documentation Projects
JoAnn T. Hackos (Paperback – Mar 23, 1994)
The original standard for technical documentation project management.

Information Development: Managing Your Documentation Projects, Portfolio, and People
JoAnn T. Hackos (Paperback – Dec 26, 2006)
An update to the 1994 classic book by JoAnn Hackos.

Microsoft Manual of Style for Technical Publications
Microsoft Corporation (Paperback – Jun 30, 2004)
Hoping for an update that includes the “ribbon bar” but certainly a must-have to save time when your own company’s style guide doesn’t address something. At ASI we use it as a fall back.

Read Me First! A Style Guide for the Computer Industry (2nd Edition) (2nd Edition)
Sun Technical Publications (Paperback – May 16, 2003)
This style guide is for those developing software documentation but not locked in to Windows standards. Also a time-saver for ending arguments over word selection or punctuation.

Letting Go of the Words: Writing Web Content that Works
Janice (Ginny) Redish (Paperback – Jun 11, 2007)
Ginny Redish’s very helpful book, related to documentation and conversation.

Envisioning Information
Edward R. Tufte (Hardcover – May 1990)
I was first blown away by the author, Edward Tufte, at a Society for Technical Communication conference, and have been in awe ever since. Nice to have on the shelf for inspiration.

Single Sourcing: Building Modular Documentation
Kurt Ament (Paperback – Nov 2002)
A practical guide to building multiple deliverables from the same content, and I don’t mean just creating a PDF of your HTML-based website, and neither does Kurt. Immediately useful.

Managing Enterprise Content: A Unified Content Strategy
Ann Rockley (Paperback – Oct 27, 2002)
Truly the must-read book for embarking on a unifying documentation strategy with content management. You learn to model the content first, an essential step.

A Practical Guide to Usability Testing
Joseph S. Dumas, Janice C. Redish (Paperback – Jan 1, 1999)
On my bookshelf as well, written by Ginny Redish, studied for my master’s degree and useful in all of my jobs afterwards.

Techniques for Technical Communicators
Carol M. Barnum, Saul Carliner
May be outdated since after all, I did finish my degree in 1995, but there are lists of suggested reading for each chapter so this book is a great resource.

Technical Editing (4th Edition) (Technical Communication)
Carolyn D. Rude
Not only a how-to guide if you’re new to editing, but also contains standard copymarking symbols for entering edits. Extremely valuable for writers being edited and editors who write.

The Nurnberg Funnel: Designing Minimalist Instruction for Practical Computer Skill
John Carroll
Difficult to get your hands on a copy, but the basis for all minimalist documentation, which applies well to single-sourcing and modular documentation or topic authoring.

Tom Johnson just spoke with Heidi Hanson for some reading ideas, and her list is a nice one too. Tom originally made me think about this question by asking about it during our STC Intercom ideas discussion and with his follow up comment, I started looking on my bookshelf.

This list is pretty textbook oriented, which isn’t for everyone. I personally like to keep up with popular business books like Wikinomics: How Mass Collaboration Changes Everything, Groundswell: Winning in a World Transformed by Social Technologies, Wikipatterns, and The World Is Flat 3.0: A Brief History of the Twenty-first Century. I read The Tipping Point: How Little Things Can Make a Big Difference during the four-hour flight from Philly to Dallas and thoroughly enjoyed it.

I’ve also referred to the Center for Information Development Management (CIDM) reading list often when I need to add a book to my summer reading list or when I know I’ll be on a plane for a long time. Although lately, parenting books have been taking over my reading time, ha ha!

The Central Ohio chapter of the STC used to have a book club, and their list of books was very useful as well, but it appears that, the place where I found their reading lists a few years back, is no more. Heidi or Jennifer, what a great idea, what happened to it? You can still access the reading lists using, though.

Here in Austin, we considered starting an STC-based lunch time book club, but didn’t get quite enough interest to push it along.

What else are you reading this summer? What texts would you consider to be classics for technical communication? I didn’t include a link the Nuremburg Funnel by John Carroll since it’s difficult to get online, but certainly peruse your used bookstores for that classic on minimalism in computer documentation, you’d have a real classic in your hands.

techpubs Uncategorized

Generation Next or Generation Y in technical communications

Upon reading my recent request to hear from Gen Next in tech comm, Julian Ramirez answered my call and wrote an excellent essay reflecting up on his experiences. He’s in his first technical communication job, working for Dee Elling, whom I interviewed about wikis and tech pubs. Thanks Julian, for offering your perspective. You may even inspire me to write a similar essay from my Generation X perspective.

Julian, take it away:

Here is a (not too brief) autobiography of my life so far growing up as a Next Gen’er to provide some personal background and an introduction to my generation:

In 1984 I came bursting on the scene, born to two loving parents in northern california. As a kid growing up I played Nintendo on a color TV and ate microwaved popcorn. I was about two years too late for Atari, I’ve never known black and white television.

In elementary school my dad bought our first computer, it was an old DOS machine that my brother and I would play Reader Rabbit on, I’m actually not sure if it was used for anything else. It used floppy disks and my dad had to write out the DOS commands onto a sheet of paper so my brother and I could start the game on our own. In 1993 we upgraded to a Macintosh Color Classic that I would occasionally use to write reports for school. Nintendo had better games though so I didn’t care much about the computer. When my family and I visited my grandmother in San Jose I would always gaze at the Adobe Towers standing tall alongside the other large buildings. I never thought that the Adobe I read about in the news could be headquartered in the town grandma lived in, there must’ve been some other San Jose somewhere, Adobe just had their name on those towers as a kind of odd billboard-type ad. The tech-bubble was growing and it seemed like all the news talked about was the latest young millionaire.

It was when I started high school in 1998 that I believe things got interesting for genY. School papers went from being optionally typed to required and my parents bought a new computer to replace our aging mac. The new computer came with a cd for some ISP, my parents signed up and I discovered the internet. At school my friends and I all had AIM and email accounts by the end of freshman year. Our parents had the Summer of Love, we had Napster and free music. Through high school I saw many of my friends’ parents get divorced, I bought my first stock, saw Y2K come and go, and the government kill our beloved Napster. The news would report on the dangers of online chat rooms and dangerous websites but us kids had already developed a cyber common sense. Towards the end of high school Wikipedia started taking off and the internet was cited in more and more school papers. Cliff notes were replaced with and my history class was online. The human genome was sequenced and the Twin Towers fell.

In college genY continued our love affair with technology. I joined friendster and facebook (back when it was still college only) and just for good measure MySpace, Bebo, and Xanga. Kazaa became popular and it seemed like everyone had Photoshop. We ditched landlines and went with cell-phones, felt guilty when we couldn’t recycle, and the library was where you went to get peace and quiet, rarely ever to actually check out a book. Smart drugs and other pharmaceuticals started showing up more and more at the college party scene. Jobs started getting outsourced to India and China, some of the same ones that we were hoping to get out of school. We weren’t that surprised by it, we grew up with “Made in China” printed on all our toys, this new outsourcing wasn’t all that different. After reading Dilbert for years and hearing about our parents getting laid off we cynically looked outsourcing as just another step that corporations will do to save a buck, the individual be damned. iPods and their white headphones became ubiquitous on campus with the question *which* one you had and not *if* you had one.

My degree is in bioinformatics, the study of data from high-throughput biological experiments, it is a multi-discplinary science that combines mathematics, engineering, and biology. It’s also a degree that could only exist today, my university had only just approved the curriculum one year before I came and it’s still only offered at a few schools. I chose it because it combines my two favorite topics, biology and technology. I took many of the standard computer science classes, learned Java with Borland’s J-BuilderX and was taught object-oriented programming right from day 1.

Almost one year ago exactly I started working my first real job. Many of my friends had already graduated and after taking some time off were starting their job hunt. I had one class remaining but decided to join them in the job hunt because the class was only offered in winter quarter and so I had about 6 months to kill. My first job was at Codegear where I worked as a technical writer few months before transitioning to my current position as documentation build engineer.

You interviewed my manager Dee Elling also about a year ago who I greatly enjoy working with in the pubs department. Despite my odd background in bioinformatics I’ve been finding it to be a very relevant degree. In bioinformatics one of our focuses is in developing tools to help researchers, as the documentation build engineer I get to use the same mindset to develop tools for our writers. Dee and I both love wikis and we’ve been working to combine her experience in documentation with my experience as being a “digital native” to experiment with new solutions to improve the quality of the help systems for our customers often using new web technology.

Oddly enough despite being a “digital native”, beta-holic and near web2.0 fanatic I haven’t been very vocal in the professional community yet. Next Geners are very aware that anything we say online lasts forever and can easily be found with just one Google search. I’ve been spending much of this past year just trying to get up to speed in the professional world and to figure out who’s who. I want to make sure that when I start talking it can be taken seriously and not just written off as some kid who doesn’t know what he’s talking about. I heard this point-of-view echoed by many of my friends in several different fields also.

STC2008 – Wrap up STC Summit trip report

I had a great time in Philly for the STC Summit, and here are some of my takeaways.

Collaboration is a huge part of our jobs, whether it’s finding others in your company to collaborate with as the two technical writers from Sun have done while creating screencasts with a “rock start developer” or the collaboration they do with users as they became community members and sometimes moderators, collaborating with the developers who use the product they are documenting. Collaboration means that you’re willing to learn another’s language, whether it’s another country’s language or learning the vocabulary of Scrum. Collaboration and structure can work together, such as the power of collaboration on a wiki, if you can find a common language (or currency), such as DITA.

My manager’s takeaway had a lot to do with Agile, and I see Agile as the ultimate collaboration mechanism for writers to integrate themselves not only with the development team, but also the business analysts who take the product to early beta with customers, and in that way, technical writers can get even closer to customers. I wrote an article for the CIDM Newsletter last year with ideas for thriving and surviving an Agile environment, so the topic is near and dear to me, but since I’ve not had to be part of an Agile dev team since leaving BMC, I chose not to focus on those sessions. I enjoyed the writeup by Richard Hamilton describing Mike Wethington’s Agile talk with each slide as a sprint followed by discussion. Agilists are living’ it, folks.

Conversation was another theme I chose to follow, due to my interest in writing a book on the topic of designing conversation and community into documentation. I was fascinated with the Asynchronous Conversation talk that Ginny Redish gave and she offered so many examples of how even the writing you do can be re-written to be more conversational – not just having style guides that allow for informal style and voice, but also removing passive voice, ensuring you know who’s the actor and what is being acted upon, and so forth. Confirmed my instinct that conversation, collaboration, and content are close cousins if we can figure out how to best combine them all.

Community is a huge part of what I have been paying attention to, and the sessions I attended and the attendees I spoke with gave me more insights into tapping the power of communities. I also found it fascinating that speakers at two different talks (Sun and IBM) mentioned finding “celebrities” when building wikis or screencasts, because communities wanted to watch the “rock star” work while they built the wiki or listen (and speak back) to their heroes while the heroes did their jobs as a subject matter expert.

Career plans and the business aspects of convincing others where your worth lives as a technical communicator were constantly brought up in the question part of the sessions. How did you prove that a wiki and screencast were the right way to take the content, when the online help had to be further minimized to do so? In our collaboration panel we were asked, what if you’re in an environment where obviously the wrong tool was chosen for a technical publications group, yet the writer felt powerless to prove the absences of ROI (Return On Investment) for that particular business and tool decision? I listened to these questions with a heightened sense of awareness of my own weakness in this area. While I can implement great ideas, proving that the idea needs to be implemented in the first place means understanding how to convince management of the value.

So, putting your manager hat on, where’s the value in conferences?

I read Tom Johnson’s notes from the conference with interest, and while I haven’t asked him this specifically, I think he and I share some struggles of attending and presenting at these conferences – we’re often invited, sometimes compensated, but it’s not our “job” to attend and present, as it is for the consultants of the world. I’m a reluctant traveler, though eager presenter. How can I justify the time and expense? Believe me, I have to justify to myself and my family before I even purchase a plane ticket, step foot on an airport shuttle, or draft up a Powerpoint slide deck.

My overall plan is that I try to go to the STC annual conference about every other year, when I’m not pregnant, ha ha. Before Philadelphia, the most recent annual STC conference I attended (and presented at) was three years ago (is that right?) in Baltimore, Maryland, and for some reason that one did not seem as “big” as this one. With probably over 1,300 attendees, Philly felt large to me, even though SXSW Interactive was probably the largest attendance I’d seen at a conference recently with over 9,000 people there just for Interactive.

Personally, I’m finding the value in interactions

I hope she doesn’t mind if I mention this, but I owe a huge thank you to Char James-Tanney who listened to my internal struggle via email while I hemmed and hawed over whether to attend the STC Summit at all this year. Working parents know that the burden is placed on the spouse at home with the kids, and my husband rocks all over the planet when they have “boy’s club” days with me. But. Family life lately has involved some funerals, minor medical issues, and just plain life, which always complicates travel plans. And then there’s things like how much really young kids grow and change in a matter of days. For example, my 18-month-old son who couldn’t reach doorknobs before I left for a conference, could open doors when I returned. And that was after a four-day trip! 🙂

Yet I have always found that the people I talk to and the relationships I forge in face-to-face meetings show enough value to make the travel hassle and lost kid growing time worthwhile. Heh, I wonder what my sons will say when they read that in ten years? I also believe that it can be good to be away from family just so you appreciate what you have when you return. I know I do.

Sarah O’Keefe and Scott Abel have been wonderful for me to simply email or call when I’m looking for mentors in this strange grey area between (not) consulting and offering expertise on the web. I didn’t necessarily have to attend a conference for these generous people to let me reach out, and it’s plain fun to get to know them.

Balancing act, of course

What I’m trying to do lately is find a balance and see what I can do to share my knowledge remotely and do a lot of blogging, emailing, e-networking, and local networking. Austin’s a completely awesome place to work and live and meet others who are forward-thinking, business-minded technical writers and managers. Heck, I can meet them for lunch, and not have to travel further than a few miles to do so. I’m also finding ways to collaborate on STC services with STCers around the world. I’d love to hear others thoughts on the balancing act and whether it changes as your life at home changes. From what I’ve observed, the long view is the most varied view when it comes to participation in STC and conferences.

What I mean by that statement is this: some of the greatest, most active STCers I’ve been fortunate to know, hit their stride when their kids went to college. I plan to be around STC for the next 20 years at least, and I’m already nearly 15 years in. STC is the kind of organization that can support that long view if my observations of others are any indicator.

techpubs writing

STC Intercom – themes and advice wanted

I’m quite flattered and humbled (and more than a little bit intimidated) to serve as leader on the STC Intercom advisory panel for this coming editorial year. We’re five people from different backgrounds and perspectives, tasked with preparing 10 themes for issues by August 2008. We’ve got academia, consulting, work-aday, future thinkers, and the only gap in our panel would be someone with regulatory or government limitations, er, opportunities for their content (applications for the open position, or suggestions for contacts are welcome!)

At our first informal breakfast meeting, Ed Rutkowski, Tom Johnson, and I brainstormed themes and topics for articles. Here’s our starting long list that we’ll work from and add to – and please, feel free to add to it in the comments!


  • Agile
  • Security (such as online identity and blending that with our user assistance systems to provide online community features)
  • Biographical or semi-celebrity feature articles, such as “how did I get to be JoAnn Hackos or Jared Spool or… fill in the blank”
  • Mobile and wireless effects on tech comm
  • Gadgets and devices (get nostalgic about the Selectric? and then move towards the gadgetry of today, hardware or software? Roll up keyboards?)
  • Outsourcing, crowdsourcing, friendsourcing
  • Eco-friendly or green themes, how do you save the planet as a tech writer?
  • Career planning
  • Location awareness – cultural sensitivity but also could be online help that knows where the reader is located geographically or awareness of where a cell or mobile phone is located
  • Messaging and brand awareness
  • Collaboration
  • Virtualization
  • Future forwards thinking, not just trends and trendsetting but really out there like flying cars kind of concepts
  • Alternatives to online help
  • Social networking
  • Usability for online help
  • Audience considerations, especially in industrial settings, high risk settings, regulated settings
  • Patterns – design patterns are used in object oriented programming but they started with architectural patterns (entry way is a solution to the problem of entering a building and a room and so on.)

I’ve also identified some areas of deficit where I’m not quite sure how to fill the void. One is, there are no Gen Nexters voices that I know of in STC yet, and I’d really like to change that somehow with STC Intercom. Gen Nexters are age 18-25, just starting out in our profession. Since now is the first time in history that four generations are in the workplace, I’m striving to find those tech writers who are just starting out but have a passion for their career choice. From what I’ve read, Generation Next is made up of 18-25 year-olds (born between 1981 and 1988). Generation X (that’s me!) was born between 1966 and 1980 and ranges in age from 26-40. The Baby Boomers, born between 1946 and 1964, ranges in age from 41-60. Finally, those over age 60 (born before 1946) are often called the Greatest Generation. Please, contact me if you are of Gen Next or could tell me of someone who I could talk with for input on our themes and perhaps contributing to an issue.


STC2008 – International Collaboration in Technical Communication

Here are my notes from the International Collaboration panel at the Society for Technical Communication conference.

Moderator Alan Houser – He’s had one day of calls with people in four different countries. Asked questions of the four panelists:
Rahul Prabhakar – Samsung currently, PC/Mac US edition, has a global mailing list, knows Korean language
Bogo Vatovec – from Slovania, lives in Berlin now. Slovenia is so small, he needed to work on international teams. Consultant for program management for different international situations
Joe Sokohl – Keene consultant, works with many varied-location team members, lived in Germany
Pavi Sandhu – Oracle doc manager in Bangalore who has started a pubs team from scratch

Q: When project is at inception, 2 scenarios – building a team up, or having a team built for you. Is the first more rare, if you have the choice of assembling your own team, what are your strategies?
Joe – we do both, some projects require location or citizenship esp. for federal US Govt consulting. There are also reasons to drive business to another shore.
Pavi – has experience building a team from scratch since he was building one in the early days before there were experienced technical writeres available in India. All the usual apply – find smart people you can train, but in another country, the criteria and testing might be different for finding those people.
How can you find a person who is equal to another in another country? You really can’t, you have to invest. You may need more experienced in another country designing and architecting, then writers who are less experienced pull the document together based on direction from the more experienced, comparative to manufacturing process. Task decomposition might be more important on an international team.

Q: How do you judge capability in an international environment?

Pavi does interviews, writing tests, editing tests.
Rahul – mentioned that recent grads might have tech com degrees from texas tech or u of georgia, but other universities might not offer it yet, waiting for the profession to mature in other countries. He believes you compare oranges to apples.
Bogo – feels assembling an intl team is like assembling a team from different companies. Team assembly only happens by talking to the person’s boss or on the phone, you can’t recruit an individual, you are only recruiting for a deliverable – so Pavi’s manufacturing scenario may need to be applied. Matching the deliverable – will the deliverable get done with the team in place.

Q: What are some effective strategies for working with intl teams? Agreement on deliverables, other strategies?
Joe – cultural awareness – unsuccess starts immediately at the initial meetings, must take stock of cultural norms, what can we affect, what can we reflect. If you host a 3:00 afternoon meeting EST, it’s 12:30 am for Bangalore, make sure you get agreement.
Bogo says that you should have respect, not necessarily understand all their cultural background. Don’t let it ruin your respect (personally and professionally) for the person.
Rahul – apart from respect fctor or getting on the same plane as other person, think about, what will it take to get things working? He learned Korean to communicate with engineers – how far are you willing to go to get the job done?
Joe – learned just enough Hindu to be able to greet, and respond, and that was enough to prove he was interested in learning about the other culture, don’t be arrogant, have some humility.
Rahul – also know about India – lots of people in India are very well-versed in the English language. He wanted to know how many people in the audience have had trouble with the speaking of Indian English.
Pavi – anectdote about language skills – that language skills are often not on par – need a process for quality control – largest circulation of English newspapers are in India (wow). Writers and editors work together, you may not get “soup to nuts” from a single writer in India. Interesting story – there were grammar and quality complaints about a manual, but when they noticed the change bars indicating what had changed when, it was the US-written content that had complaints about quality/grammar.
Alan – mentioned Adobe India which has outsourced all dev and writing to another country, full control over a segment of the companies’ product.
Bogo – problems with language is not the language itself, but the meanings of the words. Specs, when you ask for something, is it understood in the way you wanted to communicate it? Even native speakers can have misunderstandings when it comes to certain concepts.

Q: How important is face-to-face interaction?
Alan – feels one face-to-face meeting is needed, that is extremely valuable, and likely only one is necessary. Can be expensive, but seems critical.
Bobo – thinks just one face to face is not enough, you need to go out and have a beer with them. The relaxed informal setting will help build trust for later interactions. Some social events or interactions make a big difference.
Joe – There are certain personal questions that are not culturally acceptable, such as marriage status, or religion (got a good chuckle when he started asking the audience members whether they are married or what religion they are).
Rahul – story – asked a Russian writer if she had an arranged marriage, since that was what he was familiar with, she was offended.
Pavi – it’s expensive to have people fly back and forth, but even one meeting a year helps you get a sense of the person.
Joe – how effective are you with meeting technology that lets you collaborate, show your screen, talk to each other. Corporate culture may dictate the collaboration levels as well as country culture.

Questions from audience – human side, what are some strategies for dealing with culture expectations when talking about quality, deadlines? Our dischord is dijointed expectations for when work is due or what work needs to be done.
Pavi – over communicate, make sure you have a lot of meetings in the early stages of the project.
Joe – look out for “our process is right because we invented it” – make sure that you can adjust your process if it’s not quite right.
Bogo – be sure you clarify draft status, clarify what time zone that deadlines are in,
Rahul – let people know what reviewers are necessary
Bogo – don’t necessarily lean on literal interpretations “I understand” may mean just that they heard you, not that they agree with the expectations set. Some cultures don’t want to say “I don’t understand” because they are afraid you’ll think they don’t know the language. It’s not easy.
Pavi – assume nothing, overspecify, clarify, clarify.

Q: What tools have you found to be effective for collaboration?
Alan – large company in India, they have US-based area codes for phone
Pavi – webcams and Skype have been very useful, also once a month they do video conferencing with the team

Q: Questioning the quality of doc from India writers in Calcutta, they have standards in place, but the quality isn’t measuring up from the India writers, can they revisit and revise their hiring standards? What qualifications should they be looking for?
Pavi – start at the beginning, so likely the hiring was not done correctly. Make sure you can be involved at all stages. Even if you inherit a team. What certifications/qualifications? Pavi said it’s tough to evaluate even 2 people on their skill level. There are communications programs, but you need independent measures for language skills and technical skills, it doesn’t matter what degree they have.
She hasn’t been to India, but her manager has.
Joe hirers “freshers” – new people, in order to train them they way they want. Still in tech writing and usability expertise, it’s tougher to find high quality.
Bogo – key message, don’t assume bad quality because it comes from a certain country.
Question from a trainer – do I trust the written feedback or verbal feedback on training courses?
In Germany, informal mentoring and coaching goes farther than stand-up training. They won’t tell
What about turnover, retention – and what when the dollar costs are too high to stay in India? They used to have 11 writers, now when they lose one in India they do not backfill in India but rather in US.
Bogo – demand outstrips supply, hence the turnover rate. Develop a strong culture in the company so they feel affinity, loyalty to the company, respect for the management, that they’ll feel growth and challenging work. 10 is the minimal size for a team in India to keep them.

Q: What about Agile? How much are you using Agile?
Bogo – not a problem if you can adjust the setup as needed.
Pavi – Sometimes it’s just not going to work, and that’s okay. No guarantee that it will be successful, just like a local team.
Final thoughts:

Joe – Soon the adjective “International” will disappear, and it will just be projects instead of international projects.

STC2008 – Mining Web 2.0 Content for Enterprise Gold

Most definitions of Web 2. 0 are illustrative, but Michael Priestly prefers text.

He’ll pick 2 core Web 2.0 concepts for today’s talk – wikis and mashups to discuss, but there’s also blogs, tagging, social networking that could also be mined.

Wiki’s problems
Content is unstructured, you don’t know if it contains the elements of, say, a tutorial, because there’s no validation.
Content is non-standard
Content is tangled – links are easy, but selecting just a subset of wiki content results in broken links.

Problems with mashups – sources of content are standards, can’t share mashup definitions

Sum of it all – wikis don’t mash well.
You just get faster creation of silo’d content, faster creation of redundant content, faster creation of more content that you can’t reuse.
So true – “If we want others to collaborate with us on content, we usually make them use our tool.”

Scenarios he has done or is doing at IBM:
Create DITA, publish to wiki

Create DITA, feed to wiki-make those DITA pages non-editable. Example: tech support database when answer eventually moves into product docs with stamp of approval
Example: One Laptop Per Child working on collecting Wikipedia articles out of DITA to let teachers make custom curriculum that small, lightweight, portable.

Create DITA, migrate to wiki (with roundtrip in mind). Migrate to DITA is more difficult because of version history tracking.
Throw away formerly semantic content, unfortunately. Funny comparison to archeology dig – why did our predecessors bold this text? It must have had some meaning? About something? Here, the example is porting previous releases’ scenarios.

Create wiki, publish to DITA – wiki redirects edit actions to the CMS, which houses DITA, then republishes the DITA XML to wikitext using an XSLT transform. Invision is doing something like this where you edit the wiki page in a DITA editor, store it back to DITA, publish it to the wiki page. Also Web Works Publisher will publish source to wiki text (although I don’t know about getting back to DITA).

Or: native DITA wiki: portable content – move content in and out

with standardized sources, you can dependably point a tool at a wiki and get reliable source.
with added semantics, ou could make customizable travel guides in PDF format from Google maps, travel sites, combined together.

Common source for multiple wikis based on: audience, products, or platforms
This scenario provides a forum for comments on source (this is basically what Lisa Dyer is doing at Lombardi software).

When they engaged with the community while creating the content, there was a lot more activity – people wanted to “watch’ the superstars create content.

Portable content means repeatable collaboration.
Just one tool will not cut it – insist on standard-compliant tools. Blog about it, ask about it on wikis, log requirements on sourceforge – this isn’t just for vendors selling but also for the open source community. When you get something working, share your experiences with others.

IBM has a Custom Content Assembler in beta that you can try out. It uses Lotus product docs as source and you can build your own custom guides, and then choose to publish to PDF or HTML.

The conflict between structure and collaboration is solvable – use DITA as a common currency.

STC2008 – Engaging diverse audiences with screencasts, wikis, and blogs

Two Sun microsystems writers from southern Cal
Gail Chappell
Cindy Church

“Change is inevitable – except from a vending machine.” Robert C. Gallagher (author)

Audience – college age developers, industry-savvy developers working in the workforce coding enterprise apps

Documented NetBeans Ruby – tool for creating Ruby language programs, part of Netbeans integrated dev environment. Free, open-source software, means that contributions from the community are welcome, both for the product and the documentation

Survey by polling readers of their blog and the mailing lists – both audiences had the same expectations of deliverables – printed docs to learn at their own pace, also wanted screencasts, their initial assumption that only college age would want screencasts, but found that everyone wanted overviews and to see what it’s all about.

Assume that company-written docs are accurate, only trust community-written docs when they’re from a well known name in the industry. They’ll only trust blogs from well-known sources.

A plan that changed everything – content delivery as previous, writing style went from formal to folksy, nontraditional role, they went from writer to community member.

Previously they weren’t providing any rich media formats such as video or screencasts. If they added these, though, something had to be removed, so they scaled back on the online help. Their developers indicated that they always searched for info on the web.

Disadvantage – steep learning curve for the videos especially.

Came up with a plan for 3 writers online help, tutorials, blog, adding screencasts and wiki.

Screencast – video capture of the computer screen that includes audio narration. They used 3-5 minutes to introduce program features, 10 minutes screencasts showing how to build an application. Asked a well-known developer to narrate for them, Tor Norbye. Wanted to help build his persona, used royalty-free background music and rolling credits. Link to the page containing the screencasts –

Wiki – collection of web pages that users can add and edit by using a web browser. Their “rock star” Tor Norbye contributed to the wiki. Metrics weren’t high but they were coming to the wiki. Engineering originally set it up with updates. Wanted initially to put the tutorials on the wiki, but on this official website,, that’s where all the other tutorials were being placed. Use the wiki for drafts of doc instead of uploading tutorials. One way to use wiki was delivering info quickly, didn’t have to be perfect or templatized. Also used the wiki to post drafts, then emailed user forum to let them know they could review it. Once it was reviewed and vetted, transferred it over to the main website instead of the wiki. Feedback from customers on docs they’d like to see – wish list of docs, requested that the community help write those docs as well. They also searched the internet to find info in blogs, and pointed to those blog entries that were helpful.

Blog – Insider scoop from the tutorial divas, mix technical and non-technical topics, such as interviewing a student ambassador and posting vacation pictures to the blog. Include tidbits from tutorials. tips and tricks – top three ways to install on linux, tried to post at least twice a week.

Traditional docs – using company templates and guidelines. Short, focused tutorials, containing steps, screenshots, and code. Went to minimal online help. Addressed needs of global audiences and those with limited bandwidth, unlike screencasts. Kept online help to real basics, got rid of “duh” information that people could figure out on their own. Thought about posting online help files on the web, but ran into immediate problem, when they searched, they hit help topics, but users didn’t necessarily want that. Embedded feedback mechanism on all help topics, webform per topics, when it sends, it goes to every writer on the Ruby project.

Q from audience – you’re doing open source, but what about licensed software? One A from the audience, Extranet with support login IDs.

Still maintained formal style, but only for tradition docs.

“Let the authors be free to use their own individual writing style” from the developer survey

With the wiki and blog, it was much less formal, adhered to company branding requirements, but bypassed editorial review and used conversational writing style and own voice. They became trusted names as well.

Final big change – from writer to community member – new hats – writer, managing editor, first responder, community personality. When they had questions, they’d ask the community forum, which was staffed by both the Sun employees and the community members, they’d get answers quickly.

They’d search the web once or twice a week and post new news to the wiki, to keep the front page of the wiki dynamic and updated. Could provide a more varied doc set.

They enjoyed “first responder” best of all – getting the emails responded to within 24 hours of receiving it. If they had to ask an engineer, then the user got feedback right away that they’re working on it. Writer knew they were responsible for the areas for which they wrote the doc.

Looked at their doc formats and tried to figure out how to get an online identity – included their names on the tutorials, on screencasts closing credits, the blog, and the wiki. Also have their pictures and bios online.

Five major challenges –
convincing detractors – many writers didn’t want to change the way they were presenting information
overcoming steep learning curve esp. for screencasts – Tor didn’t want screencasts done on Camtasia, wanted them done on Mac program. Also a tutorial doesn’t make a good script for a screencast. Also had to record at least twice.
Finding a venue – where to upload the screencasts, didn’t want to use Youtube, not a large enough frame size. NetBeans TV is where they ended up posting. August started posting, there’s a rating system on NetBeans TV, plus post related docs and screencasts. Wanted quicktime format movies. So used, only Sun employees can post to it, but anyone can view the posts.
Watchdogging the wiki – all they do now is quash inappropriate content. If a community member has posted a tutorial and it becomes outdated, what to do? Pull it, ask the community member to update it? Mark it as “not vetted/warranted,etc?”
Combatting shyness – we’re accustomed to writing in anonymity, but had to put up pictures and their name. Made a blog that was a group blog, could encourage others to write.

Three tactics for analyzing the success of deliverables

Omniture SiteCatalyst – looks at daily unique visitors
socialmeter – determine number of social sites that link to their pages. (Hey, cool, my blog’s social meter score is over 1,200.)
User comments and ratings – part of their help system and the wiki.

Milestone releases last summer, after five months, analyzed. What succeeded, where to improve.

Screencasts – most popular was 1000 views a day, 2nd most popular was 240 views a day. 160,000 downloads from mediacast, had to open extra ports to handle the downloads. Going forward, have dev record screencasts on their own, and writers will produce screencast. Tools – IShowYou, Snapz pro. Finalcut pro for editing (“like using a sledgehammer to pound in a thumbtack”). Keycastr to record the keyboard shortcuts that appear in the upper right-hand corner of the screencasts.

Most popular tutorial was actually the written version of popular screencast with 180 downloads a day. Installing and configuring ruby support averaged 130 visits per day. Socialmeter score of 314 by end of five month period –, furl, digg, google links, reddit, shere, spurl, Technorati links.

Advanced tutorials got far fewer hits
Only one comment on online help pointed out missing/incorrect info
averaged one comment a day on tutorials, esp. getting started.
change and Ruby programming language changed their tutorials, user feedback made them aware. Fixed tutorial, blogged about it when they fixed it.
Blog results – more than 300 visits per day, top 10 blog entries are technical topics, most read were from previous project. Good for short topics, testing tutorials, building relationships with the community, and polling customers.

Wiki results – added new, edited existing. wiki daily unique visitors 65 on front page. 22 on Installation, 6 hits per day on documentation area, averaged only 11 hits per day on the whole wiki. Socialmeter score was 146, lower than screencasts. Low community participation. Need to make official web site and wiki work better together. While their wiki had only 3 community-produced docs, just attained 150 community-contributed docs. Will do usability on the front page of the wiki. Want to set up a rewards system and have a free giveaway – tshirts for tutorials.

Projects on the horizon
Vodcasts – screencast on iPod with RSS feed to iTunes. Quality is degraded, though, so they would produce file specifically for vodcast.
Books – Still a lot of value in a book; quote from a developer “to master something as complex as a new language, I want to be comfortable on the couch with no computer in sight”
Next-gen screencasts – interactive, want to stick with Mac and native OSX. Thinking of screencasts in another native nonEnglish language. They also make sure there’s a written doc that matches the screencast to make it accessible. They also show keyboard shortcuts during the screencasts. Youtube is a good venue for just faces, interview with developers at a Sun conference in Sydney.
Wikipedia – want a page that describes the technology they’re working on.

Regardless of age or experience, a developer thinks like a developer.
Screencasts, wikis, blogs and traditional written documents meet the needs of developers across generations, from college-aged developers to industry-savvy developers.
A developer can never have too much information.

… and curiosity keeps leading us down new paths.” – Walt Disney

techpubs writing

STC2008 – From Nightclub DJ to Content Management Consultant

Subtitle: Developing a Business Career The Content Wrangler WayScott Abel\'s career path at STC Summit in Philadelphia, June 2008
From the ever entertaining Scott Abel, this was an invigorating session that still kicks you in the butt to get out of your whiney mode and into a winner mode. Sounds cheesy to repeat, but it worked. Here are my notes from the session. I’d love to hear your thoughts and critique on my “live blogging” style – too much information, not enough information, not the right information? Let me know.

Routes to tech comm – English major or developers accidentally become tech writers – crafted a career – but Scott didn’t grab that URL (he’s obviously not That Scott Abel.:)

He earned 146 credit in four different programs, and didn’t earn a degree
he could get a college degree, but decided not to pay the “fees.”

Still takes classes like knowledge enabled information management – Indiana University 8-5 every day for three days, presentation to 200 people as a capstone, and you fail if you’re late, or don’t play by their rules. But it’s three credit hours.

John Herron school of art in Indianapolis – foundational school – you should have drawing or sculpting skills, though.
Business School, next stop – he lasted one semester, it wasn’t about the answers, it was about how you get the answers – answers are on the back of the syllabus

Next stop, photography – first working with digital photography, won some photography contests by accident.

Journalism school – at Indiana University – and he worked there too. He went to and helped with computer assisted journalism conference. Use computer technology to cull through all the data.

He started in entertainment journalism, friend of Margaret Cho, has interviewed Elton John, other celebs.

Started a local alternative magazine… fun exciting and profitable. Assignment in journalism school – business plan for a magazine… just did the magazine, didn’t do a plan. 72-page monthly publication, two guys with two much time on their hands – sold highscale ads and actually made revenue.

He waited tables to get through school, learning that he could make 200-300 bucks a night, he met influential people. PanAm games, miniature Olypics hosted in Indy, got more experience.

He had the attention span of a worm – didn’t lead to very many opportunities.

Became a bartender – clock in at midnight, clocked out at 3-4 am. But felt he lost time during those “young” years even though he had flexibility and enough money.

Age 14: my first gig as a DJ. Learned how to mix, taught him about content reuse and personalization… wrong song – every one hides like roaches. or perhaps on purpose, when music sucks, beer and drink sales go up.

Wrong song, wrong version of the song. He had a remix of a chitty chitty bang bang that got played on Chicago radio.

Remixes were user-generated, 45s were all they had to work with, they’d buy 2 copies of the single, because they needed songs longer than 3 minutes. So… two turntables and a mixer – had to understand tempo, tone, feel of a song, but tempo control was the key. The Technicas 1200 Turntables are still instrument of choice for many deejays.

Reuse is in the remix… that’s how tracks were laid down… vocals reused identically but combined with different styles of music.

Madonna explained how her voice could be changed, the tools allowed her voice to stretch like a proportional square stretches proportionally when you hold down shift key…

DJ mixing and increasing complexity similar to content choreography that we do with content – the technology is increasingly.

1999 – employment counselor said, you’d be an excellent technical communicator with your skill set.

Put together a portfolio

First job, documenting mortgage loan automation software, $45,000, he could buy groceries, kick out his roommates. Bedazzled by corporate America… benefits, paycheck, vacation.
Had folders called “Betsy’s documents” – totally disorganized, inefficient, wasteful, later they were sued out of business. Their automated software was

Started reading Ann Rockley, Bob Glushko, JoAnn Hackos, all of whom had really good best practices towards fixing the mess of content he was seeing at work.

Ann Rockley sent Scott a draft of her book, Unified Content Strategy, and he became technical editor on the book.

He needed a way to get organized, get away from notes on paper in his backpack, started a blog to be a storage container for his knowledge.

(Side note – I have to enter my “cringe” essays from grad school)

Once he got attention for his blog, he got more people talking to him, asking questions, help solving questions.

Started speaking at events, but then had to define his value proposition. Rebranded himself as a Content Management Strategist.

Tools that can tell management that content is valuable and that the product can’t ship without it. Value proposition can’t circle around their job – content needs to be valued.

Syndicate Conference 2006, encouraged to think bigger. He started commoditizing the site. Conference are a natural extension of what he was writing about, his readers wanted to learn more about what he was writing about.

Presenters seek attention – same folks who speak at conferences write articles and participate in groups.

Need for a community – 1900 members of the Content Wrangler community… there needed to be a way for people to connect to one another without Scott’s help.

Being an individual consultant is not scalable – and this is good news for you. You can create your own value proposition.

The discipline of Document Engineering – Bob Glushko, no future in commodity writing – the future is in solving content challenges. Structured content, XML, move content around, but not just documents – documents married with data from databases. Opens up a brand new world.

Road to success – don’t allow others to define you, no one right way to become a content management expert.

He’ll post to (youtube for ppt) (youtube for pdf) ipaper service Community site

Harmonizer product – will eventually let you analyze content using web page

acrolinxacrocheck product

How much coding does Scott know?
If you don’t know how to model content, you shouldn’t be coding. You have to be able to analyze content before you model it, even.

What’s next for Scott – providing service designs, such as RSS feeds. Problem solving providing services that give them answers before they ask them. Such as mortgage being due, or governments issuing fishing licenses.

Another question – any certificate programs you’d recommend? None, says Scott. Writing for reuse isn’t part of these certification programs, what about DITA, often focused on tools, not skill differentiators.