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.

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.

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 gail.chappell@sun.com
Cindy Church cindy.church@sun.com

“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 – http://www.netbeans.org/kb/60/screencasts.html.

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, netbeans.org, 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 –
convincingdetractors – 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. 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 mediacast.sun.com, only Sun employees can post to it, but anyone can view the posts.
Watchdogging the wiki – all they do now are quashing 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 – del.icio.us, 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, Netbeans.org 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.
Videos
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

STC2008 – From Nightclub DJ to Content Management Consultant

Subtitle: Developing a Business Career The Content Wrangler Way
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

scottabel.com – 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 dejays.

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 sqaure 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 roomates. 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 scaleable – 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.

Questions?
He’ll post to slideshare.net (youtube for ppt)

scribd.com (youtube for pdf) ipaper service

http://thecontentwrangler.ning.com Community site

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

acrolinx – acrocheck 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.

STC2008 – Writing as an Asynchronous Conversation

I had high expectations for Ginny Redish’s talk at STC this year, and she did not disappoint. It was wonderful to have my ideas about conversation and technical communication vetted and couched in academic terms such as linguistics, pragmatics, and so forth. Here are my notes. Please let me know if this is useful to you and if you have any suggestions for my liveblogging skills.

Writing as an Asychronous Conversation
Ginny Redish

Our conversation is synchronous – at the same time.
The term Asynchronous means at different times.

Book = Letting Go of the Words

Conversation as a theme for all we do as technical communicators.

Asked – how many of you have a different degree other than technical communication? Nearly everyone raises their hands. Ginny’s background is linguistics.
Exploring – all the new social media ways that technical information is shared through written conversations – participatory media as discussed by Harold Reingold in the keynote session

Boundaries – not discussing Skype or VOIP (it’s synchronous and it’s not written, it’s voice), not talking about IM or chat because it’s synchronous, not talking about AI (computers talking, Eliza).

Think about a recent trip to the web – why did you go, what were you doing? How much was that a conversation?

Caroline Jarrett’s model of forms – appearance (looks), conversation – jam in the middle of the sandwich (how it talks with the user), relationship (does it set up trust, credibility?)
We’ve been writing these for a while… UI, Error message – dialog boxes are conversation

The conversation is often prefaced with “How do I?”

Think of conversation as turn taking – it’s not always explicit, but you’re anticipating questions – implied conversation. Example – “What’s in the box?” – Hardware includes a SIM card (implied next question, “What’s a SIM card?” placed in a textbox) Last question after listing all the contents of the box, “Missing something?”

Another example – bulleted list “If you want to do this, here’s how” It’s a conversational way to do things, and there’s research to show it. Doesn’t have to be questions, can be “If/Then.”

Not this – Issuance of a TOP command results in a line zero condition.
This! To go to the beinning of your file, type TOP and press Enter.

Linguistics research on pragmatics (language in use, the context) The context may cause the utterance to have a meaning. Speech act theory – in many cases the spoken words are not taken literally, but you must understand the meaning behind the words.

4 maxims of conversation from Wikipedia – Gricean_maxims
If these are violated, cooperation/agreement declines.
Deborah Tannen – sociolinguist, misunderstandings because of the meta message behind the message – cultural, gender understandings.

Do not make your contribution more informative than is required – minimalist principles.

Person 1 – I’m low on gas.
Person 2 – There’s a station around the corner.
Assumptions – they’re in a car, that it’s a car fuel that they’re talking about
What if Person one responds, I know that, but I left my wallet at home – repairing the conversation. In writing, we have to anticipate the conversation so well that we think about how the conversation is interpreted and the user’s next question and response.
Person 2 has reason to believe that the gas station is open and is selling gas.

Next conversation – a good one or not? NO
To exit the program, type Quit and press Enter.
Be sure to save your files before you do that.
Actual example from a manual that Ginny has reviewed.

Implications of following Grice’s maxims:
know your users, what they know, and their context
think about interpretation (write so as not to be misunderstood)
realize that context changes
turn taking – give and take turns

Examples from Caroline Jarret, open university web forms
points – what are points, do you need them to graduate or to enter the program?

Pat Sullivan, Purdue University – dissertation from Carnegie Mellon, read only as far as what they thought would solve the problem.

Write with first things first – context first.
Approved fumigation with methyl bromide at normal atmospheric pressure in accordance with the following procedure, upon arrival at the port of entry, is hereby prescribed as a condition of importation for shipments of yams from foreign countries. (paraphrased)

Give and take in conversation
are pieces of info right sized for what user wants a s a chunk – too much (fire hose, wall of words), too little at a time (have to click Next too often)
are questions grouped logically

LiveValidation example:
Say “hello” to LiveValidation (form box)
if you don’t type fast enough, webform responds “How come you’ve not said ‘hello’ yet?”

CHI to HHI? Should it be not computer-human interaction but human-human interaction through the computer?
Tee hee, right when Ginny asked, are information products going away? Her slide show went on screen save mode.

More people go to Google than the user manual – should you spend resources contributing to the customer forum instead of expecting users to go to the manual?

Future of information for students – ? textbooks replaced by spectrum of web pages

Think “conversation.”
write conversations.
Facilitate conversations.

Can online help show “read wear?”

I’ve been re-reading Jakob Nielson’s Participation Inequality essay on useit.com, and the suggestion to some how show wear marks on content struck me this evening for some reason. I guess it’s because I’ve been working on Drupal recently, and discovered that Drupal documentation contains site recipies in the Drupal Handbook. What a nifty idea. Stick with me, these two concepts are related through a recipe and cookbook angle.

Part of Jakob’s treatise on inequal participation in online communities is that you can do little to overcome the typical contribution stats of 90-9-1, although one of the suggestions is to make participation so easy that you don’t even know you’re contributing. Case in point – Amazon’s “people who bought this book, bought these other books” recommendations. Sounds like the easiest contribution ever – data mining and analyzing, then giving the data back to the shopper in an understandable format.

Jakob says, “Will Hill coined the term read wear for this type of effect: the simple activity of reading (or using) something will “wear” it down and thus leave its marks — just like a cookbook will automatically fall open to the recipe you prepare the most.”

What are some similar examples of displaying read wear from the online help or user assistance world? The first example that comes to my mind is a wiki’s “most active pages” feature that shows the page with the most edits. However, the page with the most edits may be more controversial than truthful, so the most popular pages would be more useful than touting pages most active.

How else can you show read wear on a website? You could also show the most searched-for terms when the user searches. Concepts may be more easily connected when you understand what others were searching for.

Or, rather than showing search terms, show the most recently viewed knowledgebase articles or most popular articles. I know I’ve found that useful in the past when searching through BMC Software’s rich knowledge base.

Just like CNN and other news sites offer a listing of the most emailed stories per hour, you could show the most emailed online help topics if your system offers the ability to email topics.

The ability to rate an article is included in many online help systems, and exposing the ratings to the reader would help in determining how “well-worn” a help topic is.

Tag clouds can display read wear as well, as I just realized while looking at the WordPress FAQ starting page – tonight, the largest tag is “Images.”

I’ve distilled it down to popularity, time spent on the page, rating on a page, and number of edits from strongest to weakest indicators. What other factors matter in an online help system?

Finding and following conversations – applicable for technical writers?

Bryan has the following ideas for finding and following conversations, and I think these are quite applicable to our role as technical writer also. The only item I find wanting in his post is – what keywords do you use? My initial ideas are: product name, keywords for the problems and solutions that your product addresses, and company name. Perhaps even the job titles for people who use your product like I’ve blogged about previously.

Finding and following conversations

1. Search on Google Blog Search
2. Search on Technorati
3. Use an RSS reader such as Google Reader
4. Start subscribing and listening to podcasts through iTunes
5. Subscribe to Google Alerts
6. Reading blog comments
7. Jump onto Twitter and establish a presence in Facebook

I found an excellent case study of technical writers engaging in conversation through Dee Elling, who is the tech pubs manager for a programmer’s IDE. She has a blog post called Help on Help where she gets lots of comments from users – some of whom are in her camp, others who are ready to go to battle for the help content, namely the code examples that had mysteriously disappeared between releases.

Dee answers honestly and really empathizes with their need for those examples, and has a plan in place for replacing them. Her blog post is a great case study for how to have ongoing conversations with your customers.

I’ve been thinking about the writer’s interaction with customers a lot lately, because of blogging and podcasting and wikis other social media pursuits that seem to lead us towards documentation as a conversation with customers. As Tom Johnson found in his Web 2.0 experiment, some users think that the help system has boundaries. How can we break down those boundaries (seems like search is part of the answer)? How could Tom have ensured that his customer sought out conversation rather than answers?

Giving the subject matter expert a voice

I just completed a three mile run with the voice of Joan Benoit Samuelson in my ear through the techonlogy offered by iTunes and iPod and Nike’s iTunes store.

Joan Benoit Samuelson is a famous US female marathon runner, and winner of the first women’s Olympic marathon. She is most certainly a subject matter expert for female long distance runners. She gives relevant tips during certain sections of the 30 minute mix of music and voiceover tips from Joan, from how to find a pace to relaxing your shoulders and finally discussing how to vary your foot stride depending on the terrain, flat or hilly.

I couldn’t help but think of how this is an excellent example of how to incorporate subject matter expertise in new ways – it’s sort of a podcast mixed in with a mix of excellent music. Now I’m wondering how screencasts could incorporate subject matter experts voice-overs, or perhaps ways of having a “famous” subject matter expert be involved in your wiki through article contributions or just commenting every once in a while. And a podcast mixed in with a screencast offering might be a neat experiment.

Tom Parish just pointed his Twitter followers to a great blog post about Nike’s community strategy and how well it’s working. I’m a complete believer in what they’re doing. Plus, I think this example also shows that some of this community building only can happen with experimentation. Nike basically allows the community to use the platform as they wish. For example, one of the unexpected things that happened is that runners found each other for runs in real life, and quickly. Plus, the online communities that are popular are the ones where people challenge each other, such as College X vs. College Y.

Community as an added value for the technology. Neat.

I just had to share how helpful it can be to have a true “famous” recognized expert insert or splice their contributions into regular content. As technical communicators, perhaps we can enable or design that sort of voice or community into our deliverables.