just write click

Alan Porter’s presentation at the Central Texas DITA User Group meeting talked about Quadralay’s use of wikis internally and their external wiki at wiki.webworks.com.

They have four wikis in operation right now, with one more to come. Back in 2003, they started their first wiki for the development team. Their company is a small one, based in Austin, and they now have absolutely every employee (with the exception of one person) having contributed to the wiki at some point or another. Currently, with their staff of 15 people, half of them contribute several times a week.

They held a brown bag training session for the whole company when a wiki for the company came out, to help people get comfortable with editing.

At their WebWorks RoundUp user forum last year, they demonstrated a proof of concept that they could take a mix of FrameMaker, DITA-XML and Word source and turn it into wiki text. I was at the demo and it has such a nice “cool” factor even if it was a simple Proof of Concept (PoC).

Another case study - they use their wiki to communicate with clients and customers on the bid and contract process, and people say it makes things go so smoothly with great communication. They use the very secure MoinMoin wiki engine and it is locked down with tight controls.

The WebWorks Services wiki:

• used to create and track task tickets
• offers single point of contact
• facilitates interaction between customers and engineers
• gives a timeline for edits on a page
• gives them milestones and percent completion

In the next six months or so, they’re planning on a new doc site, docs.webworks.com (not yet live) to be authored in DITA using structured FrameMaker, then published to wikitext using WebWorks.

Steve Carl already wrote up his notes from BarCamp Austin and I enjoyed his viewpoint very much. This was only my second BarCamp experience, and this year, I decided to take the plunge and actually volunteer to present. Whurley was very encouraging despite my inexperienced questions. “What’s a badge that you wear vs. a badge for your blog?” for example. There are graphics for each, as it turns out. The graphics are completely awesome, and the t-shirts were great, arriving despite an actual train derailment preventing the first shipment from arriving on time.

For those not familiar with the BarCamp format, it’s an unconference where you show up in the morning and put your session into one of the time slots on a white board or on a post-it note. The wiki also had sign-up schedules but the hand-written timeslots at the event win over the wiki page.

The week before BarCamp, I went to the wiki’s Sessions page, clicked the Edit button, and wrote up a short description of a session called Hug the XO. I basically wanted to see if others could bring their XO laptops and I could show them the tricks I’ve learned recently, plus run the Sugar emulation on my Dell laptop.

Getting to Idea City

(photo by Chad Hanna from theotherpaper on flickr)

The morning of BarCamp, getting to BarCamp turned out to be more difficult than I had planned. I got downtown by 9:00, but couldn’t find the Silver Dillo to ride over to 6th and Lamar to GSD&M’s Idea City. So, I took a few touristy photos of Ester’s Follies and the row of SegCity’s Segways, turned around and went back to the Austin Convention Center. I attended a 10:00 SXSW Interactive session, Creating Findable Rich Media Content, and then went back to Sixth street seeking the ‘Dillo. I walked about five blocks until I was past Congress Avenue when I saw a Silver Dillo sign and a person waiting at the sign, then turned and looked up the street to see the trolley coming our way. I double-checked with the woman waiting to make sure there wasn’t a charge since I was silly enough to have not gotten cash out, and sure enough, it’s a free ride. I boarded the Dillo and was on my way.

Getting into BarCamp

Idea City itself is an incredible workplace, full of creative vibes and a wonderful open design with full windows in front. Steve Carl greeted me, I registered with a cool registration application that Twittered my arrival to @barcampaustin (very cool), I had my picture taken for the flickr photo stream, and Steve and I proceeded to the schedule board to see where I could fit in my pres. I really felt more like doing a demo than a full-fledged presentation, so I was happy to see that the demo room had a free half-hour slot at noon. I drew little XO icons on a post-it, titled it “Hug the XO” and headed upstairs to figure out the room layout. On the way up, I saw my old BMC buddy Cote, and ran into Decibel, a good friend of my husband’s, and also met Snax finally, having friends of friends of hers.

Hugging the XO

In the demo room, I hooked up my laptop and ran the Sugar emulation image downloaded from the RedHat Site by using QEMU. In emulation the Activities run pretty quickly, and it’s very easy to display on a large screen. There’s discussions surrounding a projection display for the XO itself, but it’s easiest to emulate for me.

I showed Turtle Art which is really exciting to programmers. People expressed an interest in showing the XOs at Codemash because there’s a grassroots Kidsmash that happens in parallel, so I’ll definitely be following up with Josh on that idea.

I also learned some neat tricks to get deeper into the XO. One way to view the files on the flash memory without using a command line is to launch the Browse Activity and type file:///home/olpc/ as the URL. Now that is a handy shortcut.

I also learned that you can transfer files to and from the XO by using scp from the Terminal Activity by reading the XO setup user guide at OLPC Austria. First, get the IP address by typing iwconfig at the prompt. Then, you can use these instructions:

To upload the file test.py from a pc to the xo (into /home/olpc), use: scp FILE_NAME USER@IP:TO_DIRECTORY

scp test.py olpc@192.168.0.2:/home/olpc

To download the file /home/olpc/xo_test.py from the xo to a local pc, simply reverse the arguments:

scp olpc@192.168.0.2:/home/olpc/xo_test.py ./

We finally got the Acoustic Tape Measure Activity working correctly, and I’ve updated the instructions on Floss Manuals appropriately. Test your task instructions, I always say! Fortunately, this was a fun one to test. We had to have the laptops beep at each other at least 4-5 times before the measurements came into a reasonable range, starting out at nearly 200 meters, and eventually settling on just over 3 meters. Success! The noise they make to each other almost sounds like they’re spitting at each other. Kids will love this activity with a pair of laptops.

People really enjoyed the Speak Activity and we laughed to discover you could give it multiple eyes.

I think we had at least a dozen people stop by the demo room, and after the demo session was over, we set up two of them near the lunch pickup line. Steve was nice enough to “babysit” the XOs while I went back to some afternoon SXSWi sessions, and he said he thinks at least 100 people got to see and try out the XOs for themselves. We downloaded Flipsticks, played some Tam Tam Jam, showed off the Browse Activity, surfing to any URL we needed to, and generally had a great time. We met other XO owners and I told them about the XO-Austin users group, and told everyone they could meet us at Las Manitas on Sunday for an XO meetup. I’ll write another story about my lunch meeting with SJ Klein from OLPC, Robert Nagle, the XO-Houston user’s group organizer, and Melissa Hagemann from the Open Society Institute (OSI). We had a great time together.

Summing it up

This experience was such a great opportunity for me to talk to people about things I believe in (kids, technology, and education) while having fun being a technical writer. I was intimidated initially because I’m not a programmer, and so I wondered if I’d be questioned for even volunteering to present, but I realized that no matter how technical I was, I would be less technical than someone in the room and more technical than someone else in the room. So, the correct action to take is to share the knowledge you have and listen to others to learn more about the topics that interest you.

My only regret from BarCamp is not staying longer for Dawn Foster’s talk about Community Management. I had asked my husband to meet me at the Convention Center with my two sons so we could go to Screenburn together, but after seeing how intimidated my four-year-old would have been by the shoot-em-up video games there, I cancelled on them and wished I had stayed at BarCamp longer. I’ll just have to settle for reading Dawn’s notes about her BarCamp experience instead.

So many sessions that I want to attend, but at least sched.org lets me select more than one session at a time. Such an awesomely simple interface and login is so quick, just an email address and a password and you’re scheduling in no time.

I’ve also put an invite out on upcoming.org to anyone who wants to meet with other XO users to come to Las Manitas for a late Sunday lunch. Thanks tantek for the photo.

What can you teach with the XO laptop? I’m still pondering that question for US-based classrooms. I’m reading the news from Birmingham Alabama and the blog entries from Dallas-Fort Worth Texas school systems with interest. Apparently you can buy a certain minimum of XO laptops if your school district or other group wants to incorporate them into their learning activities. Sign up at http://wiki.laptop.org/go/Laptop_requests. With some grassroots fundraising efforts, a large-scale purchase of XO laptops seems attainable, perhaps even for Austin ISD.

Last week’s post with a picture of my four-year-old using the XO at our dining room table generated a response that a picture shows it all. I’d say that these pictures capture even more of the spirit of the OLPC project, showing a preschool teacher and two students have a blast with them, taking pictures of themselves, each other, and even taking pictures of the others’ XO.

I’ll also attest to the durability and sturdiness of these laptops. My son was walking quite quickly in the classroom with it (okay, maybe even running, but it’s not like he runs with scissors!) and tripped and fell with it. He was unhurt, these kids bounce back unbelievably from falls, and I was equally impressed with the complete durability that the XO displayed even when it probably took a bounce on the carpeted classroom floor.

So, what am I teaching with the XO?

My first session with the kids focused mostly on TamTamMini and Turtle Art, both auditory and visually appealing. These are four-year-olds, so they’re a little young for the target age for these laptops. The target age is about 6-12 years old. But, they figured out the touchpad quickly (and some, like my son, want the touchpad to allow for a mouseclick event when tapped like my Dell laptop responds, but not so with the XO touchpad.)

The kids also crowd around the screen and want to touch everything, which is fine, until I want to do the Turtle Art demonstration which involves clicking Project, and then clicking the icon for Samples and then waiting and then opening a sample file. But they were rewarded for their hands-off stand-off with bubbles and rainbow colors.

In Turtle Art, I thought I’d always have to open the Blocks menu and drag the “clean “puzzle piece out, then click it to get the full starting effect. However, I just discovered that many of the samples have the clean block out already, it’s just hidden behind the menu. I finally figured out to click the hide, erase, or stop buttons to have the turtle stop mid-way through his task. The kids liked the Turtle Art demonstration as well and asked for more. I must admit, I didn’t feel like I was teaching them anything, but these are four-year-olds. With repetition and some more ideas we could build several learning opportunities around that Activity, I believe. I just got a great PDF file showing how to make the turtle draw letters, and I intend to use this demonstration for my next visit.

The next session I attempted to get the Acoustic Tape Measure Activity to work, but it failed miserably. I think it’s because I didn’t go to the Group view and Invite the other XO to the Activity. We’ll try again another day, after I’ve done some more testing.

I also introduced the Record Activity and this was a huge hit for photos. I didn’t show them how to record audio or video, thinking I’d save that for another day. The pictures it takes are 640 x 480, and quite nice with natural lighting. See examples at the XO Photos group on flickr. In a future update of the XO, EXIF data will be available on the photos taken with the XO, and Flickr can then identify the source of the photo as an XO. I’ll have to upload some of the photos the kids took.

One kid even took a picture of his behind with it, reaching way back to push the O button on the game keypad (a nice shortcut way to take pictures with the Record Activity so that you don’t have to use the touchpad and X button click!) His teacher and I laughed so hard at his ingenuity and problem-solving - just to get a picture of his bottom.

Who else has taken their XO into a classroom setting, and what are you learning and teaching with the XO? I’d love to hear more, and I’ll be at SXSW Interactive and BarCamp Austin as well so please do say hi if you see me there.

There are two upcoming Central Texas DITA User Group meetings that you don’t want to miss if you’re looking into wikis for documentation.
Jan. 1/23/08

Ben Allums, Quadralay - wiki.webworks.com

Chris Almond, IBM - internal wiki

Anne Gentle, OLPC - wiki.laptop.org and www.flossmanuals.net

Ragan Haggard, Sun - www.opends.org/wiki

Feb. 2/21/08

David Cramer, Motive - internal wiki

Lisa Dyer, Lombardi - internal wiki

Alan Porter, Quadralay - wiki.webworks.com

The January panel will talk about models for information development in a wiki framework – a couple of case studies with a demo of each system to illustrate use cases/workflow/high-level architecture. We’ll have a discussion of how these models might empower our professional community.

Ragan Haggard presented Delivering Open Source Technical Documentation via a Wiki at the San Antonio STC chapter this month, and his slides are available for download. My favorite slide is number 17 - and I have his permission to quote it verbatim here.

Why not resist this fad?

• Removing barriers to input from SMEs greatly
improves the documentation.
• These docs will get even better with feedback and
input from real users.
• We writers have no less control over the content
than before.
• A wiki has as much or as little structure as you
impose on it, the same as a book.
• I don’t think this level of collaboration is a fad.

We should have a lot to talk about and perhaps even a homework assignment between the two sessions.

It was easily 80 degrees in Austin today, but I so enjoyed a Christmas performance tonight despite the lack of cold or snow. The Yellow Tape Construction Co. is putting on The Ultimate Christmas Musical - The Musical at the Salvage Vanguard Theater off I-35 near the University of Texas in Austin. I laughed and laughed and I’ll leave it at that since I’m no theater review writer. But you’ll thank me for telling you about it if you go, and you’ll thank me for the laughs you’ll get from their blog (and they twitter too!)

Where else could you see an elf chasing (or being chased by?) a group of people on a Segway tour of Austin but in Austin? I challenge you to come up with a better picture of surprise Christmas spirit than this.

Happy holidays to all and to all a good night.

Next week I’m speaking at our local Austin STC meeting about wikis and technical documentation. Here’s the relevant information if you’re in the area. Interestingly, Scott Abel of The Content Wrangler is giving his Web 2.0 talk at the Quadralay WebWorks RoundUp that afternoon as well. It’s a Web 2.0 world for tech pubs folks in Austin next Tuesday. Hey, I just noticed that Quadralay has started a Blogs area on webworks.com, great!

Here’s the logistical information for the meeting in Austin next week:

A Technical Writer’s Role in Web 2.0 - Wiki-fy Your Doc Set

Anne Gentle, senior technical writer at ASI International and blogger at http://www.justwriteclick.com/

How can a wiki be used to build user-centric, user-maintained technical documentation sites that offer thorough and accurate technical information? More than two years ago, I issued a challenge to my colleagues to send me examples of technical documentation in a wiki. I was skeptical that wikis could be used in a meaningful way for technical content. Through tips from coworkers and word of mouth, I found several wikis to study for the types of content that can be placed in a wiki and try to derive best practices for when, why, and how to start a wiki.

Where: Commons Center on the J.J. Pickle Research Campus, Austin, TX

It’s near the corner of Braker Lane and Burnet Road. There’s a map of the campus at http://www.utexas.edu/commons/maps/index.html.

When: Tuesday, November 6, 2007

6:00-6:30 PM: Networking

6:30-7:30 PM: Program

7:45-9:00 PM: Networking Dinner at the California Pizza Kitchen at The Domain

I’d love to see you there!

I’m happy to report that my article about using wikis for technical documentation was published last week in the STC Intercom.

A PDF my article is available for anyone to download, STC member or STC non-members alike.

I’ll be giving a presentation about wikis for technical documentnation to the STC Austin community on Tuesday November 6th at the Commons Center, which is located at 10100 Burnet Road, Austin, TX 78758, near the southwest corner of Burnet Road and Braker Lane on the University of Texas J. J. Pickle Research Campus. Map

If you’d like to see what else I’ve written about wikis, take a look at the articles in my wiki category, or check out this list from my talk.bmc.com blog.

So many people helped me with the Intercom article. Kelly Holcomb is an excellent editor and helped me with it in her small amounts of spare time. Emily Kaplan read an early copy and also helped me sort through my notes. Michael Cote has sent me interesting items about wikis that he has found and also constantly tags useful information in del.icio.us. Diane Fleming was investigating wikis on her own, asked me about them, and then gave me great feedback on an early copy of the article. Tom Johnson was extremely positive when he first read it as well. I spoke with Dee Elling who had two excellent experiences to talk about in her interview with me. Harry Miller had a podcast interview with Molly Bostic, the PM on the MSDN wiki team, that was very informative.

It takes a community to write about online communities. Thanks, everyone!

My employer, ASI, gives employees three hours a month to use to do volunteer work of your choice, and I’m busy thinking up ways to use that time. After Hurricane Katrina, I spent a half day at the Capitol Area Food Bank, using some hours that BMC gave to employees to spend their time helping Katrina evacuees. In a half day, four of us processed 8,400 pounds of food which can make 6,720 meals. So I might try to do that work again. It was interesting and I learned a lot. I’d also like helping out kids or parents, so I may investigate areas where the local school districts use volunteers. I also like that our local NPR station, kut.org, has a Get involved page.

Working at a company that enables non-profits has really made me want to learn about our users and how non-profits work. I found this game online called Karma Tycoon, where you run your own non-profit. It looks like it’s sponsered by Chase. Also interesting reading lately has been about non-profits in Second Life. I haven’t tried Second Life yet, mostly due to lack of time (I’d rather be blogging).

So if you’re knowledgeable about non-profits, membership management, church organizations, and so forth, let me know of websites and books that you find useful. And if you have good ideas for three hours a month of time spent volunteering near Austin, TX, let me know. I’ll keep you posted on my efforts.

Right before the World Congress on Information Technology commenced last week, Austin mayor Will Wynn pushed a big white button in front of a coffee shop downtown, and 28 wifi access points gave access to an area extending from Town Lake on the south to 7th Street on the north, and from Lamar Boulevard on the west to I-35 on the east. That’s nearly 18 blocks by 6 blocks, we’re talking about 108 square city blocks of wireless access. Yet another great reason to call Austin home. Here’s the news story, Downtown wifi network goes live. In June, the network expands to East Austin, and in July, Zilker Park will join in.

I wonder what sort of service level they’ve agreed to for this network. Apparently Google’s Mountain View Wifi efforts hit a snag, requiring installation of more access points. I know from hearing about wireless installs at the dinner table that thick concrete walls, strange valley and rock formations, and even bushy trees can make for a touchy network. Sure hope the Zilker Park additions are well-designed and architected as there are plenty of interesting rocks, trees, and waterways there. Are customers more lenient about wireless access than “regular” network access?