Tag Archives: collaboration

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.

Wikipatterns, the wiki, the book, teh awesome

I’ve gotten a review copy of WikiPatterns (the book) in the mail and I want to review it here and make sure everyone who reads my blog knows about this book and the WikiPatterns website. It’s a guide to getting the most out of your wiki and the most from collaboration with the people you work with via a wiki. Combined they offer such a great resource.

I admit, I read the Questions and Answers first, even though it’s near the end of the book. I guess I wanted to see how Stewart would answer the questions I hear from others. I enjoyed his answers and comparing them to how I’d answer. I think I’m in agreement with him 100%.

Next I went through choice Case Studies, starting with Leap Frog. There are loads of case studies and they involve internal and external wikis. One thing I noticed while reading the case studies is that the case studies refer to the patterns and anti-patterns by name, so you must refer to the wikipatterns.com website to study up on ’em to get the most out of the book. You should refer to it regardless of your use of this book, it’s just that good.

Lots of fascinating tidbits in the case studies, though. I didn’t know that Leap Frog was an Agile development environment. Their internal wiki is named “Emma” which is cute to me, and apparently was better than naming it a wiki project. Good pointer.

Next I read about the author. Turns out, Stewart Mader and I both have Chemistry degrees.

Which led me to the foreward. Ward Cunningham, the inventor of the wiki, wrote an excellent foreward that will inspire you to become an activist, wiki-based or otherwise. And he reminds us that we humans crave collaboration.

Then, I boggled at an entire chapter dedicated to proving that Wikipedia’s perceived “problems” will not transfer directly to your wiki implementation. Thank you! Thank you! I’m not alone in trying to go against the anti-Wikipedia sentiment applied to other wikis especially for technical documentation such as end-user manuals.

Next, I moved on to the examples of wikis in use. Wow, wiki as peer directory. This is an excellent use that I wouldn’t have thought of until it was spelled out for me in this book. Collaboration works best when you know the person. And knowing the person in a global company often means only finding out about them through their profile page. At BMC, we used editable Sharepoint pages to upload pictures for remote stateside team members and writers based in India, which helped us get to know each other better on a personal level. It makes it all the easier to ask about the weather or a certain family vacation before diving headlong into some technical topic or project hurdle with a team mate.

Also, wiki as meeting agenda opener-upper. I loved adding agenda items to a Sharepoint site when I thought of them, rather than trying to remember them and send them in an email to the right person before a meeting started. That’s exactly what goes on a wiki. Things that you don’t want to trap inside of an email, nor do you have to wait until an email is sent out requesting agenda items.

So there you have it – my review of an excellent book that is a carry-around edition of the wiki with the same name. While it works well with the wiki, it offers more than the wiki alone contains.

Specialized information hoarding

I get the greatest blog ideas from my lunch companions lately. This week it was a few former BMC writers. At BMC, the writers have an annual book exchange around the holiday time, and it was so popular we sometimes repeat it mid-year.

At our book exchange, everyone would bring a wrapped book, place it in a pile, then draw a number out of the hat. The person who drew the lowest number would chose from the pile, unwrap the book, read the description, and then the person with the next number would choose to either “steal” the already unwrapped book or take from the pile. The person who drew the highest number would have many unwrapped book titles to choose from.

For a few exchanges in a row, Jonathon Strange & Mr Norrell appeared in the book exchange pile, so all four of us at this lunch had read and enjoyed the book very much.

Could you hoard all the information on a topic if you wanted to?

uspbkjacket_w150.jpgJonathon Strange & Mr Norrell is a wonderful fantastical story about the return of magic to England due to the two people in the title (well, and due to other forces). There are humourous parts, and the fun of the book is that each magician has a very different approach to learning magic again. One hoards all the books about magic. ALL the books. This aspect of information hoarding was especially interesting to us writers at our lunch discussion. Could you even do that in modern day – collect all the books about a certain topic (albeit a narrow focus?) No way.

Another observation is that the cautious one is the one who hoards all the information and only very reluctantly shares it with his reckless pupil. I’m working on a panel discussion on collaboration and I can’t help but remember this book and how fruitless and unsuccessful it was for Mr Norrell to attempt to keep all the books on magic in a single library. The similarity I would draw is how difficult and unhelpful it is to try to write all the information and hoard your topics, never to be remixed into other deliverables.

If the information is hoarded, how is it released to the wild?

Another story that came up in the same week of lunchtime conversations was one from Don Day. He has had a certain camera since he was in high school, and never knew that much about it. He has taken it apart numerous times, and looked for books about the camera, searched on the web with all the identifying text he could find inside the camera, and tried to find any additional information about it, but never found out more.

But! This past year, when someone (I believe the book’s author) uploaded several chapters from a book about specialized vintage cameras to the Internet and it became indexed by Google, Don learned that his old camera that he couldn’t previously identify is worth a couple thousand dollars! It was like the TV show, Antiques Roadshow, had delivered an appraiser to Don through the Internet.

Don’s love of cameras comes full circle in the information sharing sense. Don maintains a wiki about cameras called “Light of Day” and has wonderful photos there. I like this quote from Don’s bio in a wiki entry about the Central Texas DITA User’s Group meeting for October. “I work in high tech, but I love simple things, which is why I feel that an early camera, made of leather and wood, but fitted with a precisely-polished lens, is such a great complement to my own life experience.”

With these two tales of information collection, I hope you see the beauty of share and share alike. Any one else have a great story of information suddenly revealing itself? Or a tale of an information hoarder who met with trouble?

DITA and wiki – w/ho/w will (we/you) write

I received an excellent question from a reader about his eagerness to use wikis for his product’s doc set, but he came across conflicts and issues when he questioned the practicality of maintaining a wiki for his large set of documentation. Here’s Paul’s well-phrased request for information.

I am considering using a wiki for documentation projects, but have been coming across some showstopper issues. Here is the story:

Our documentation set is large. We only want to maintain one set of files. Therefore, any changes in the wiki would need to be automatically synched with the source files.

The obvious suggestion is “just make the wiki your source files.” However, it is not as simple as that, for a few reasons.

  • First of all, we need to generate attractive offline documentation in online help format, viewable across several operating systems. No wiki enables an elegant way of doing that.
  • Secondly, we have a bunch of conditional text–our existing documentation comes in six different versions. I have not found a good way to integrate the different conditional tags into a wiki, while maintaining it in both our sources and the offline output files.
  • Finally, wikis almost by nature do not support DITA. Wikis are designed to be simple and easy to understand. However, that approach negates many of the advantages of structured writing.

For these reasons, I currently see wikis primarily as a collaboration tool. But they do not have the features necessary for complex technical documentation.

Do you have ideas for how we could get around these issues?

Oddly enough, on this particular day, another reader wrote in about similar issues with wikis, but they have started to overcome them. He listed the issues succinctly, saying:

I’d say that there is quite an art to creating wiki doc from a couple of perspectives:

* conversion
* building out the infrastructure
* look-and-feel issues
* style issues
* review issues
* basic editing issues

Even with all these issues — 🙂 — however, the immediateness of the experience, the ease associated with making changes and the creation of links and containers, and the modern look and feel really make wikis a fascinating competitor with other, much different technologies. How many other industries move off in such opposite directions (wikis vs. dita)? It’s sort of like trying to figure out whether cars should run on gas or steam!

The CEO of Confluence came through a few weeks ago. He was pointing out to the following as an example of a company that had developed wiki doc:

http://www.gigaspaces.com/wiki/dashboard.action

Here are two more you might find interesting if you don’t already know about them:

http://docs.codehaus.org/display/GROOVY/Documentation

http://www.aptana.com/docs/index.php/Main_Page

And here’s the part that is amazing to me – in a follow up email, Paul answered some of his own questions and said that the gigaspaces.com wiki is one wiki he is investigating further. For example, by talking to one of the writers, he learned that their wiki has 1300 pages, and reuses many pages through the [include] command or transclusion, which is the inclusion of part of a document into another document by reference. My original response to Paul talked about DITA as source files and wiki as an output from those source files. I learned that Robohelp does something like that, with source files and wiki as output, and this blog post mentions round-tripping the content back to Robohelp.

Naturally, I have some ideas about DITA and wikis. My post about DITA Storm built into a custom wiki describes a hybrid approach, with DITA files as the source and editable pages. Paul takes that idea one step further, saying that you could have the internal technical writers see a DITA editor interface to the wiki, but have end-users write doc in a simplified editor with fewer tags. I like that idea.

There’s also the possibility of a transform from DITA to wikitext. A search on the dita-ot-developer list on sourceforge.net revealed that Deborah Pickett was writing such a thing for her employer last April. I emailed her and she generously gave me her XSLT source files, but said that she gave it up when she found that “The whitespace rules for wikimedia meant that anything fancy would end up being better written in wikimedia’s pretend HTML format anyway.” Hm. I haven’t tried the transform yet myself. Bob Doyle has done a lot of DITA to WikiMedia transformation to pre-seed the ditawiki.org with content, and he says “The Perl script for conversion to MediaWiki is publicly available at http://www.jtidy.de/conv. It has a major flaw in that it does not convert URLs to hyperlinks.” Again, I’d need to try it myself to see whether that approach would work and if the technology scripting is worth the effort.

Now, for everyone pondering wikis and DITA, an absolute must read is this great article by Paul Prescod, The Convergence of Structure and Chaos. Not that it offers practical solutions (although he hints at some at the very end), but it maps DITA concepts to wiki concepts.

I’ve also been noticing that people are trying to automate getting content from their support forums into wikis… Check out this poor intern’s daunting task: http://ask.metafilter.com/62679/Automated-Media-Wiki-Page-Creation.

I guess to answer my own question about where wikis fit in tech doc, I currently see wikis as supplemental, not source doc from which to make other things. I probably lean towards seeing a wiki is another output from perhaps DITA source. Sure, there would have to be a loopback mechanism to get the contributed parts of a wiki back to the source files, and I’m not sure how automated that could be. But, I would love it if vendors could convince me otherwise, and frankly, I keep hearing about Confluence and their examples are compelling.

So I share with you these side conversations I’m having in hopes that the information here helps others in their quest to offer wikis to their end-users. Users, write the manuals. But make sure us writers get to meet our objectives as well.

As a final departing thought, I share the machine is us/ing us video, containing the best description of Web 2.0 and new media I’ve seen to date, created by a cultural anthropologist. It’s about five minutes long, and a thought provoking piece.

One of the questions in it that stuck in my mind was the question at about 3:00 minutes, “Who will organize all this data?” And the typed and re-typed answers after a screencast or demo of del.icio.us:

We will.

You will.