Tag Archives: STC

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!

Ideas

  • 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.

Upcoming wiki talks in the central Texas area

Next week I’m presenting at the Alamo STC Chapter, giving a talk titled “A Technical Writer’s Role in Web 2.0 — Wiki-fy Your Doc Set.” It’s at the Igo Library in northwest San Antonio and you’ll want to refer to their website for directions. It’s Tuesday February 12th with the presentation starting at 7:00.

I plan to update the presentation from the last time I gave the presentation at the Austin STC chapter and I’ll post the slides to slideshare when they’re ready. I’ll take it out of Google Presentation format and go with PowerPoint since the 800 x 600 display was pretty dismal using Google Presentations. It’s too bad because sharing that presentation was so easy.

The week after next on Wednesday February 20th, the Central Texas DITA User’s Group is continuing the wiki panel discussion we started in January with three more speakers talking about their wiki experiences, including one wiki that uses DITA as source. Here are the presenters:

The networking starts at 7:00 with the panel starting at 7:30. It’s at the Freescale campus on Parmer and directions are available on the DITA wiki. I’m looking forward to this presentation as an audience member as well to learn about more wiki best practices and DITA conversions to wikitext.

A Technical Writer’s Role in Web 2.0 – Wiki-fy Your Doc Set

Next week I’m speaking at our local Austin STC meeting about wikis and technical documentation. Here’s the relevant information if you’re in the area. Interestingly, Scott Abel of The Content Wrangler is giving his Web 2.0 talk at the Quadralay WebWorks RoundUp that afternoon as well. It’s a Web 2.0 world for tech pubs folks in Austin next Tuesday. Hey, I just noticed that Quadralay has started a Blogs area on webworks.com, great!

Here’s the logistical information for the meeting in Austin next week:

A Technical Writer’s Role in Web 2.0 – Wiki-fy Your Doc Set

Anne Gentle, senior technical writer at ASI International and blogger at http://www.justwriteclick.com/

How can a wiki be used to build user-centric, user-maintained technical documentation sites that offer thorough and accurate technical information? More than two years ago, I issued a challenge to my colleagues to send me examples of technical documentation in a wiki. I was skeptical that wikis could be used in a meaningful way for technical content. Through tips from coworkers and word of mouth, I found several wikis to study for the types of content that can be placed in a wiki and try to derive best practices for when, why, and how to start a wiki.

Where: Commons Center on the J.J. Pickle Research Campus, Austin, TX

It’s near the corner of Braker Lane and Burnet Road. There’s a map of the campus at http://www.utexas.edu/commons/maps/index.html.

When: Tuesday, November 6, 2007

6:00-6:30 PM: Networking

6:30-7:30 PM: Program

7:45-9:00 PM: Networking Dinner at the California Pizza Kitchen at The Domain

I’d love to see you there!

The “Quick Web” for Technical Documentation

STC Intercom article “The Quick Web for Technical Documentation”

I’m happy to report that my article about using wikis for technical documentation was published last week in the STC Intercom.

A PDF my article is available for anyone to download, STC member or STC non-members alike.

I’ll be giving a presentation about wikis for technical documentnation to the STC Austin community on Tuesday November 6th at the Commons Center, which is located at 10100 Burnet Road, Austin, TX 78758, near the southwest corner of Burnet Road and Braker Lane on the University of Texas J. J. Pickle Research Campus. Map

If you’d like to see what else I’ve written about wikis, take a look at the articles in my wiki category, or check out this list from my talk.bmc.com blog.

So many people helped me with the Intercom article. Kelly Holcomb is an excellent editor and helped me with it in her small amounts of spare time. Emily Kaplan read an early copy and also helped me sort through my notes. Michael Cote has sent me interesting items about wikis that he has found and also constantly tags useful information in del.icio.us. Diane Fleming was investigating wikis on her own, asked me about them, and then gave me great feedback on an early copy of the article. Tom Johnson was extremely positive when he first read it as well. I spoke with Dee Elling who had two excellent experiences to talk about in her interview with me. Harry Miller had a podcast interview with Molly Bostic, the PM on the MSDN wiki team, that was very informative.

It takes a community to write about online communities. Thanks, everyone!

Hyperviews Online article about CMS for website

Here’s a link to my latest article on Hyperviews Online, the newsletter/blog for the Society for Technical Communication Online Special Interest Group (STC Online SIG). It’s called Using a Content Management System (CMS) for your STC community web site.

The STC Austin chapter is re-designing the community website, and I volunteered to help. We started researching CMS use and I found that quite a few sites were using WordPress, so I emailed the webmasters to learn more. The article is a result of that email survey where I learned more about WordPress as a CMS.

Contributing to wikis as a technical writer

I’ve been researching an article for STC Intercom about wikis and technical documentation as discussed in my previous post. In about two years of my interest in the topic, I have only discovered a handful of examples of wikis used for end-user documentation for a technical product. And sometimes I even stretched the term “technical product” to include all of eBay. Heh.

If you’re also interested in wiki research, I have also been compiling bookmarks of blogs or websites that comment on wiki use on del.icio.us too at http://del.icio.us/annegentle/wiki.

Anyway, here’s a list of the ones I’ve found as good examples so far, but my criteria are loose and fast, such as recognizable products or geeky products. I’m sure there are more, and this list of the top 57 wikis based on popularity offers an even longer list.

But instead of soliciting more examples, I want to ask a few more questions myself. How many of these wikis would I use to get an answer to a question? Probably all of them. Now, how many wikis have I contributed to? How about you? If you haven’t ever contributed to a wiki, why not? If you have, tell us which one, and what motivated you to contribute?

Wiki for tech pubs – ready for main dish status? Or still undercooked or side dish material?

Wiki Wiki Teriaki neon signWiki Wiki Teriaki neon sign, Austin, Texas

I’ve been doing some research for an article for the STC Intercom based on the interview I did with a friend of mine who does maintenance on the MOTO Q wiki. The article will come out this fall and I can’t wait to see if any rousing discussion appears on the STC forums. In the meantime, I want to continue to blog about wikis because I want to continue to research their use in the technical publications world.

I have had an interest in wikis for technical documentation for a couple of years now. There are a couple of good discussions on wikis for technical documentation from February 2007 on Tom Johnson’s I’d Rather Be Writing Blog as well as The Write Time blog. Tom’s post talks about using wikis to help with the documentation process. In response, there’s a wonderful entry by Lars Trieloff about exactly how a writer uses wikis for technical documentation.

While my STC Intercom article doesn’t talk about the internal wikis I’ve used for documentation tasks, as an Agile team member, I did find that the wiki housed information while development was ongoing and I also edited pages to keep them updated as I discovered something in the code that didn’t match the wiki.

It’s funny, in an early blog post I wrote on the internal blogs at BMC I said that I did not see how wikis would be used successfully for technical publications. I have since changed my once low opinion of wikis but I still see them supplementing other documentation, not substituting completely for technical documentation. I’d welcome discussion about wiki as standalone or supplemental end-user documentation. What do you think? Should the merits of wiki for certain products win out as the exact right documentation for that particular product especially one either related to an Agile methodology or social media? Or are wikis relegated to an upgrade to the customer support forum with a kludgey way of entering the information and no good method for outputting an information deliverable worth reading?

Best practices in technical documentation

If you’re in Austin, you’re welcome to attend the Society for Technical Communication meeting where I’ll be moderating a discussion about best practices for documentation.

I’ll be moderating a discussion Tuesday night at one of our Society for Technical Communication chapter meetings. I found this article, “Tech writers as sales reps? Interface Software’s award-winning docs boost brand, revenues, and customer satisfaction” and thought it has some great points but I really wanted to get the opinions of others in tech comm to see how well it holds up in reality. The title sure promises a lot, doesn’t it? It’s an excellent read.

Our meeting announcement made it into the Austin American Statesman in their “Tech Week” section, so that’s exciting. Here’s their announcement: The Society for Technical Communication will host a panel discussion on the practice of technical communication. Speakers will be Wendy Shepperd, information development manager at BMC Software Inc.; John Gough, principal technical writer for Troux Technologies Inc.; Cathy Mallet, information developer at Motive Inc.; and moderator Anne Gentle, information developer at BMC. 6 to 8 p.m. MCC, 3925 W. Braker Lane. Free. www.stcaustin.org.

If you’re local to Austin, come on over and listen in on our discussion. I don’t expect we’ll figure it all out in an hour or so, but these articles and topics sure do get folks like me thinking. Feel free to chime in here on the blog as well about your opinion on these best practices.

Summary of best practices

#1: Create a healthy workplace.

#2: Understand the value of good documentation.

#3: Use documentation to gain an edge.

#4: Have a reasonable ratio of writers to developers.

#5: Place technical writers somewhere sensible in your org chart.

#6: Keep technical writers in the loop on development plans.

#7: Encourage technical writers to meet customers.

#8: Use customer advisory boards to get feedback on documentation.

#9: Make the right tradeoffs.

#10: Pick the right medium for each deliverable.

#11: Provide print for those who need it.

#12: Give your writers the right tools for the job.

#13: Try out conditional text.

#14: Explore single sourcing.

Bonus tips

Bonus tip #1: Hire writers with the right stuff.

Bonus tip #2: Hire writers who ask smart questions.

Bonus tip #3: Don’t get hung up on tools.

Bonus tip #4: Provide lots of feedback.

Bonus tip #5: Insist on timely reviews of drafts.

Bonus tip #6: Enter publication competitions for feedback.