Tag Archives: writing

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

DocTrain West 2008 – Darren Barefoot – Social Media 101: Now Everyone’s a Technical Writer

Here are my notes from Darren Barefoot’s talk, a self-described recovering technical writer.

He leads with what defines social media? Create your own definition around these concepts:

  • Conversation – comments on large media sites allow ayone to speak to the media person keeping on the pedestal
  • Collaboration – 7 million people collaborating on wikipedia, likely the largest collaboration in human history
  • Sharing – some sort of microbroadcasting is built into every type of website
  • Scope – there are no longer 42-minute hours on televisions. Your buckets of stuff and time are sliced and diced. Ebooks can be 10 pages to 1000 pages.
  • Community – constructing affinity groups is easy, accessible
  • Transparency – blogging encourages transparency – medium is the message
  • Authenticity – example of knowing it’s fake is fakeSteveJobs.com, Lonelygirl15 is an example of outed fakery

42% of Chinese internet users have a blog

“The people formerly known as the audience”The people formerly known as your audience

Survey of 1200 bloggers – why do you create content, do social media? Talk to friends and family first, Keep personal history, Emote top three. But make money bottom response.

How to use a Wiki – video showing how to collaborate without using email (yay).

Updated to add: How to use Twitter – video showing how friends use twitter to keep up with each other between blog posts (these are awesome videos, I now love commoncraft)

An excellent, engaging talk, with the conclusion being, there’s no way to relinquish control, it is already too late.

Here are the takeaways he left us with:

  • Relinquish control – realize that the best documentation for your product is already not on your website.
  • Users will help each other – put screenshots in Flickr to make it easy for your users to grab them and use them in their own doc
  • Empower your most passionate users – for example, the Red Room Chronicles created by a Marriot business traveller. He must be the most passionate hotel user known. Offer those users previews, invite them to focus groups, make them feel special.
  • Think outside the page – Twitter troubleshooting tips, and of course, remember video and photos.
  • Go where your users are – find their community spaces, be present as needed.
  • Relinquish control – again. 🙂

Putting content into context in a wiki – especially in a large environment

An interesting read on the front page of wordpress.com of all places. I enjoy random clicking, and this one came up with a great commentary on the difficulty of using a wiki to get how to information.

From Learning about Second Life from Google:

Over at SL, the main source of information is on the WIKI, which in my opinion has some great information but because Linden primarily lets the users run the show isn’t as helpful as some sort of information clearing house. Trying to sort out how to sculpt, for example, is an exercise in total frustration. There are some wonderful tutorials, but SL does nothing to properly aggregate and put these tutorials into context.

I wonder what Second Life could do to properly aggregate those tutorials to meet this user’s needs? I suppose long-time wiki writers would answer: use categories and encourage tagging, while looking out for orphans. Any other ideas?

I got a great question from Tom Johnson of I’d Rather Be Writing:

I’m just wondering if you have any thoughts on the WordPress Codex, http://codex.wordpress.org/Main_Page. Yesterday I was looking at this Codex wondering what to make of it all. I think I want to be a contributor, but there are so many topics. It’s chaotic. The organization is like a maize. I don’t know if I should go in there with a wrecking ball and rennovate, or not. Probably 25% of it is outdated. What happens to those outdated pages? Will I offend people if I just delete things that are outdated?

Can you recommend a book or strategy for making sense of massive wikis? Where should I start? I spent a good hour editing a page of it last night that I considered critical. It’s then that I realized this is a huge project and I have no sense of direction. Any insight you can give me would be much appreciated.

With the OLPC wiki, David Farning on the Library list went through the wiki and said he found these categories. It’s quite an accurate content analysis from what I’ve seen, so I was impressed. At the same time, it also helped explain my initial wonderment at how to wrap my arms around the entire wiki – and in fact, it is barely possible to do.

Content
1 Philosophy
2 Contributing
3 Creating
4 Curatoring

5 Projects
Deliverable
In progress
Ideas

6 Management

Once David came up with these categories, he then asked SJ Klein, director of community content and long-time Wikipedian, if he thought the wiki needed structure.

SJ said that the wiki is purposefully without hierarchy – flat, especially for projects, to not force a parent or sibling sense for projects. He also said, however, if you have a specific tree hierarchy in mind, feel free to develop the idea in some temporary space.

So, when working on a large wiki if you have good organization ideas, set them up, and then ask for community feedback. Seems like an appropriate approach to a large wiki.

Other ideas for starting out in a large wiki environment:

While it might seem like it’s a question similar to “how do I get started on a huge writing project?” in my experience, wiki editing has some subtleties due to the collaboration and community vibe already present behind the pages. You have to work harder to figure out that vibe, and then determine your course.

For new people, there’s the whole question of getting a feel for the community so you can start to answer “who am I going to potentially irritate by editing this” and “as a newbie do I have the confidence I’m right?”

So, knowing your role within the wiki community is a first step. You might take a while to get to know who’s there, what their roles are as well, and where you might best fit in. Introduce yourself with your profile page, following the WikiPattern, MySpace – see http://www.wikipatterns.com/display/wikipatterns/MySpace.

Just like a newbie on a writing team, find out if there’s some scut work that you can do to get your feet wet, if needed, to gain the community’s trust.

Deletions are going to bring much more wrath in a wiki situation, I would guess, so they seem risky to do to start out. If you do think something needs deletion, message or email the original author or the big contributors and ask if it’s okay to mark it for deletion. Then, mark it, and hope that someone else (a wiki admin) determines if it should be deleted.

Start small, like tagging, or applying templates. That’ll help you get a feel for the bigger picture.

Let us know your ideas for wrapping your head around a large wiki, we’d love to hear them.

Here Comes Everybody: The Power of Organizing without Organizations

I’ve listened to about the first 45 minutes of Clay Shirky’s talk on “Here Comes Everybody: The Power of Organizing without Organizations.” http://cyber.law.harvard.edu/interactive/events/2008/02/shirky. Well worth the time spent – especially for my current employer’s product set, which enables organizations to manage their data used to communicate with and connect their members with each other through event planning – all the goals that associations and non-profits strive for every day.

My favorite example, since I’m fascinated with wikis for documentation, has to do with setting up a community of practice faster than ever known in history. On Flickr, a group dedicated to High Dynamic Range photography became a popular destination and learning and collaborating connection.

Before the web, it would have easily taken five to seven years to build up the community – starting from the time when a professional photographer figured out the technique, to the time when ordinary people having the knowledge to accomplish HDR. Using Flickr, it took three months to build a community of practice, because when a photo goes up, people talk with each other, ask how photos were done, and examine the photo examples to learn. In this case, the technology became a platform where people help one another get better.

This group has no commercial incentive whatsoever, as a side note.

The community is as important as the content, a humbling thought for us writers. Just like the Architecture of Participation that Tim O’Reilly talked about in 2004, the participation of community members to generate and test content is as key as the content itself. He even states, “the fundamental architecture of hyperlinking ensures that the value of the web is created by its users.” Google Page Rank further adds to the value by including inbound links in its ranking algorithm.

On The Content Wrangler site there’s a great post asking where does user participation fit in our world? There are plenty of answers, and my interest lies in the case studies that show the amazing power of what results when users actively participate. If you’re interested in user participation and social networking, check out Tom Johnson’s interview with Scott Abel about social networking.

Stories from SXSWi 2008 – Attracting girls to IT

15% of people are from the northeast
15% of people left handed
15% of people in the world have no cell phone, or no Internet
And… less than 15% of computer science majors are female. [1]

This was the lead-in for the panelists and I liked the tie-ins of 15.

Since this session, I have talked to girls around the 12-15 year old range, and I completely agree with all the panelist’s observations about how girls don’t think they’re good at something, especially computers.

In this session I met Ashe Dryden and we talked about BarCamp Austin – she’s an organizer for BarCamp Milwaukee. I asked her to watch my laptop while I got a “pop” and offered to get her one too. I laughed when she asked upon my return, “Where are you from, if you say ‘pop!'” I have lived in Austin seven years, but haven’t let go of my Midwestern roots (Indiana and Ohio), where we say pop for all kinds of soda, pop, soda pop, Coke, and fizzy drink. 🙂

After the session I spoke to Clare Richardson of GirlStart about how the Austin XO user group would like to help out with their projects. One that’s upcoming is the Take IT Global showcase, where they’re working on games for the OLPC project. It sounds like they have enough XOs for their upcoming event, April 26th, which I plan to attend. They’re going to show off the educational game projects that the girls in the GirlStart program have been programming. They’re using a wiki to keep notes, collaborate, do project planning, all for the work they’re doing on their games. It’s great fun to read the game ideas.

Here are my notes from the session.

Clare Richardson – GirlStart in Austin, TX
What class in middle school did you feel smart and confident in?
art, phys ed, math, computer lab?

TechBridge
Free afterschool programs and summer programs.
Role models are key, role model training. Great training document available on their website. I plan to read through it for ideas on taking the XO to classrooms.

Jay Moore MentorNet
Email connection with mentors, 10-15 minutes a week.

Abby Tittizer IBM Extreme Blue
Internship program, not specific to women, for college students.

Q: What are the common misconceptions about girls and technology and getting them interested?
A: Perception is boring and nerdy and you have to already be good at it. Girls have altruistic missions.
Girls don’t think they’re qualified to do something, but boys “just go for it.” girls think that an internship means they already need to know how to do it.

Suggestions:

  • Have girls sign up in pairs for a computer class.
  • Spend time with your kids teachers and guidance counselors to find out more about their science education, etc.
  • Boys tend to have an inflated sense of their own competence.
  • UT has a club that has a roadshow that goes out to TX high schools to help recruit.
  • They use pair programming in introductory classes.

Updated to add: There’s a great article in the NYTimes that I found through Anne Zelenka‘s del.icio.us links called “Sorry, Boys, This is our Domain.” While girls might not be computer science majors, they are excellent bloggers and customizers of all sorts of web and social sites. Quote: “…a study published in December by the Pew Internet & American Life Project found that among Web users ages 12 to 17, significantly more girls than boys blog (35 percent of girls compared with 20 percent of boys) and create or work on their own Web pages (32 percent of girls compared with 22 percent of boys).” Girls may have more patience and perseverance to stick to a site that requires content updates.