Category Archives: wiki

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

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

Collaboration with asynchronous communication – getting to know “you”

While gearing up for different conference trips and presentations, I’ve been trying to get to know collaborators using asynchronous communications, such as listening to Char James-Tanny’s podcast on techwritervoices.com. She presented “Virtual Ways of Communicating” at a Florida STC meeting and Tom Johnson recorded it and posted it later.

I really enjoyed not only listening to Char speak but also hear the audience questions and interactions. For example, when she showed tag clouds, one audience member asked, does the size and format of the tag words change when a tag is used more often than another? And I thought, wow, I’ve always assumed that is exactly how it works, but haven’t actually asked the question, such as refresh rate or what relative sizing means. It points out to me that I take a lot for granted in the Web 2.0 world due to observing so much of it so often. But, a new fresh perspective offers me the conceptual details that people would seek when first exposed to something like a tag cloud.

As part of listening to this podcast, I found many suggestions for cool videos, popular wikis, and new uses of RSS such as RSS that I hadn’t heard yet. I realize that no matter how hard I try to keep up, there are new applications of technology coming in every day. I thought I’d collect these together though as a nice collection of “have you seen this?” which may not make much sense unless you listen to the podcast, but these were enjoyable to hear about and explore on my own.

Ready for DocTrain West

I’ll be at DocTrain West in Vancouver next Tuesday-Friday moderating the Meet the Bloggers session as well as co-presenting Wiki Roundtripping? Structured Authoring? How Do They Co-Exist? with Stewart Mader.

I just put the finishing touches on our Wiki Roundtripping presentation and I have to admit I’m a little excited about it. While much of the focus will be on the DITA-Wiki Hybrid scenarios, there are at least two new scenarios that I’ve learned about since writing that white paper that we’ll bring to the presentation.

The Meet the Bloggers session is apparently going to be popular, so I hope I can pull off the moderator role effectively. I’m no Oprah, but I do come from Cincinnati where Jerry Springer was once mayor. This session will be fun and I expect to learn from Tom Johnson, Scott Abel, Darren Barefoot, Scott Nesbitt, and Aaron Davis.

Plus, I’m excited for the Unconference sessions Wednesday night. Completely experimental, but this conference seems like a great place to try out some different ways of sharing information off-the-cuff and informally.

Edited to add: Alan Porter was even inspired to update the Wikipedia entry for unconference to add a definition. That addition is very useful. Way to go Alan!

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.