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 –
convincing detractors – 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 program. 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 is quash 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