Since I write user assistance for a living, I’m naturally drawn to the devices the Google Wave team is implementing in order to teach people how to use Google Wave.

For me, there were a few waves in my inbox from the start. First, Doctor Wave, impersonating a Bill Nye the Science Guy character appears in the “Welcome to Google Wave” wave as an embedded YouTube video, and points to different areas on the screen while embedded in a Wave. It’s a nice welcome and a great navigation aid to the user interface, very clever in that the perspective is as if he’s talking to you from the inside of the interface. I liked it despite my normal reluctance to take two minutes and twelve seconds to watch a video about something I need to understand better. The video won’t be nearly as effective outside of the Wave, but you could still learn from it if you view it in YouTube instead of in the Wave.

From embedded video to try-and-see to blog entries

Next I started clicking around, and was naturally drawn to my Contacts to see who else is on this invitation-only site? The ones pulled from my Gmail contacts were nearly all from OLPC, since that account is my main email account for that project.

After that, nearly all of my learning process came from Mashable’s blog entry titled Google Wave Guide, and videos about using Google Wave. I also studied their entry titled “Testing Google Wave: This Thing is Tidal” before getting my invite. One of the best “getting started” guides is also by Mashable. Wow, how did Google get third-parties to write their Getting Started Guide? In reality, the Mashable blog entry also serves as a map to the Google help itself, by pointing to the list of Advanced Search terms for Google Wave, for example.

Only after logging on for another two or three times did I find a Google Wave FAQ, written as a wave. I think this FAQ is a great example of documentation when you need it, simplified and task-oriented.

Mostly I am learning by exploring. Last night, Char James-Tanny set up a public Google Wave for STC, the Society for Technical Communication, called STCWave. I found it by searching for “with:public STCWave”. By using that Wave I was able to add more technical communicators to my contacts list, especially those that I didn’t have a Gmail address for previously.

Agile team collaboration tool

I have to wonder aloud if Google built Wave as an essential part of their development teams’ collaboration arsenal. Real-time collaboration is so important to being successful at Agile. Having searchable archives of team decisions and team discussion can be extremely helpful, and photo and document sharing can help a team “gel” so well. We’ve been using Etherpad and Campfire for text-based discussions and some file sharing as well as shared document editing.

Search integration

I have also found it essential to know some basic search phrases to help you find Waves that will be useful to you. One is “with:public” (no space after the colon). With that search delimiter you can find all Waves with public users invited, and other user names and group names can be substituted for public. You can search based on participants, creators, the state of the wave (such as read, filed, and muted), and the types of attachments in the Wave.

Being a student of the Wave

So what are the best ways to learn Google Wave? I think that conversational and community teachings are the way of the Wave. Text is still a huge part of learning, yet printed artifacts are not (yet) a part of learning Google Wave. Video and screencasts are proving to be made by many people.

And finally, learning by experimentation is how many of us will learn Google Wave, especially since its access is to a limited release and invite- or nomination-only web application.

Update – The Complete Guide to Google Wave is now available. A purchase of the print copy goes to a great cause.

I’ll be presenting a webinar on Thursday September 10th at 1:00 EST about collaborative authoring techniques.

Here’s the session description: Groups can take action even quicker than ever before in history thanks to tools that amplify group communications such as wikis, blogs, forums, social networks, and instant messaging. There are distinct levels of collaboration that a group can attain and what they accomplish directly correlates to the level of collaboration.

• Information sharing – Finding information as any technical writer does, via email, phone calls, interviews, and so on. A brief collaboration exercise shows the power of information sharing.
• Cooperating – A discussion of Agile development techniques to help shape a web application and online help going with it. Introduces the use of wikis for documentation.
• Collaborating – A case study of how a new in-person collaboration method called a Book Sprint is run with subject matter experts identified and working together to create an information deliverable, with FLOSS Manuals‘ wiki platform as an example.

You can register on the STC site and the cost is $79. So gather people round the conference table at noon Central time and let’s talk about collaboration!

This post was contributed by Kelly Kilpatrick, who writes on the subject of online colleges and universities. She invites your feedback at kellykilpatrick24 at gmail dot com.

According to the Bureau of Labor Statistics, there were 49,000 technical writers in the United States last year. They also say job prospects are best for technical writers over all other types of writers. So, why are so many people just coming out of college with technical communications degrees having a tough time landing that first job? It can be completely frustrating for both new graduates and prospective employers who have vacancies and feel the talent just isn’t there.

Let’s look at some of the skills and education required for technical writers and then examine why entry-level technical writing jobs are few and far between.

Some of these include:

A degree or certification in technical communications.

Often a background in another technical field such as engineering or science and may specialize in a technical area where they have expertise.

An ability to create, assimilate and convey technical material in a concise and effective manner.

In technical writing, even more than in other fields and industries, you need experience to get the job. A technical communications degree is a very good start but many companies (often led by engineers) doing this sort of hiring see writers as ill-equipped for the job and seek a more technical background to “prove” they can handle the job. Writing skills aren’t enough and even knowing the lingo and the software used are often not enough. So, what’s a new technical writer to do?

Here are some ideas:

If you can, take some engineering or computer science classes. If you’ve already graduated, take some continuing education classes to bolster your knowledge.

Offer to do a small project on spec (unpaid) for a company, or seek out volunteer work, such as documentation for an open source software project. You get a portfolio piece if nothing else and the company or organization for whom you did it may be willing to keep you around if they like what you’ve done.

If you’re a more creative type, learn how engineers work and think. They are very linear, literal and see few gray areas in anything. If you can learn how to talk to them in their language, you’ll be more successful.

Like anyone starting a new profession, you’ll need to take smaller or lower-paying jobs in the beginning as you build your portfolio and gain experience. This takes time, but if you decide you can stick it out, you’ll find a wealth of opportunities in a field that’s got nowhere to go but up.

Lifted in whole from the December 1, 2008 OLPC Community update – what a neat story.

Cambridge: Samuel Dalembert, the 6-11 starting center for the NBA’s
Philadelphia 76ers, is a devotee of technology whose personal foundation
supports a variety of youth projects. Samuel attended the OLPC country
meetings in May. Recently, he was watching an episode of “House” on
television when he saw a G1G1 spot. Samuel immediately volunteered to do
a commercial for us, too. He will also make sure that XOs are deployed
to support his projects in his native Haiti, the Dominican Republic and
elsewhere, and will encourage other NBA players to get behind OLPC.

Better late than never, I suppose. I’ve had these notes on my hard drive and want to post them to the cloud of my blog.

John Hunt, DITA Architect in the Lotus Information Development Center at IBM and DITA Learning and Training Content Specialization SC chair, presented Using DITA Content for Learning Content Development at the April 2008 Central Texas DITA User Group meeting. He gave an overview of work being done on the new Learning and Training Content specialization that will be part of OASIS DITA 1.2 release. (Updated to add: see DITA Learning and Training Content Specialization SC for additional information and download links for the Open Toolkit Plug-in that contains the approved specialization.) He then followed up with a live demonstration of creating, assembling, and delivering topic-based learning and training content, delivered both as a SCORM-compliant package and as simple XHTML.

In the room we had about 20 Austin attendees and on the phone, a handful more in Ann Arbor, with John Hunt, our presenter, presenting from Massachusetts. He has worked with DITA for 9-10 years, but interestingly, has met Don Day in person only once.

Learning specialization will become a DITA standard in next OASIS release.

John led with a very recent newspaper article, about re-creating the Jefferson Library – “Re-created Library Speaks Volumes About Jefferson” Amy Orndorff, Washington Post, Apr 11, 2008 (John’s talk was on the 16th!) The library was given to the Library of Congress for $24,000 in 1815. Jefferson had created his own taxonomy – memory, reason, or imagination. Automatically, John wondered if you could parallels to reference, concept, or task. Ah ha!

Fascinating – Jefferson did mashups of books by tearing them apart, even different language books, and then would bind them into new books – reassembly of content 200 years ahead of his time.

Industry context – trends – smaller, faster, leaner for creating and delivering training content.
Content as reusable learning object helps… RLOs (Reusable Learning Objects) were developed at Cisco in the 1990s, similar to legos as building blocks – different structures with the same set of Legos.
LCMS (learning content management system) came into being.

Training can move from a “craft” approach to a DITA content approach, standard.
Craft = every deliverable unique, every context one-of-a-kind
Craft = presentation oriented, labor intensive
DITA = content and deliverables have consistent structures and patterns, so available for reuse and repurposing
DITA = collaboration and reuse becomes the norm

IEEE LOM (Learning Object Metadata) is a standard for the learning metadata domain. See ltsc.ieee.org/wg12/20020612-Final-LOM-Draft.html
Build maps + specialized processing = generated learning deliverables such as tutorials, courseware and e-learning, ILTs, SCORMs=mandated for training delivered to the U.S. Govt. (Dept. of Defense), Textbooks. In case you’re wondering, SCORM stands for Sharable Content Object Reference Model – SCORM is a set of specifications created by the Advanced Distributed Learning initiative (ADL). The ADL website has that SCORM runtime freely available, see www.adlnet.gov/downloads/.

Learning objects contain:
- Instructional objects: overview, content, summary, assessment
- Informational objects: concept, task, reference, also known as Facts, Concepts, Procedures, Principles

5 new DITA specializations as learning types – learningPlan, learningOvereview, learningContent, learningSummary, learningAssessment

Midnight at the OASIS – 32 members on the sub-committee, working drafts, Lang. Spec available for inclusion in DITA 1.2 (Nov 13, 2007)
Specializations of 5 topic types.
Also, three domains are available:

• Learning interactions domains – open question, true/false, single select, multiple select, matching, sequencing, hotspot.
• Learning map domain – learning objects and groups, makes learning content available for use in any DITA map
• Learning metadata domain – makes learning metadata available for use in learning topics and maps.

What does DITA bring to learning content?
Consistency all around (content, processing, delivery)
Can grow as DITA grows – add a Flash object

DITA vision – a platform for collaboration

DITA specialized tags contain “lc” for learning content – lcAudience, lcObjectives, lcDuration, lcPrereqs, lcChallenge (instructions follow that address that challenge), and so on.

Manifest file informs the navigation that is then imported inside the zip file into a sample run-time environment – Advanced Distributed Learning. Has Suspend and Quit buttons, as well as Previous and Continue buttons. Assessment section has questions, true and false with javascript that lets you find out if your response is correct or not.

He showed an embedded Youtube video using the DITA object tag within the Summary object. See Double bonus slide for embed code.

Q: Are you re-inventing the wheel with DITA since scorm and ilm are already standards.
A: Scorm is a packaging and delivery standard. Scorm is silent with regard to content.

Eliot Kimber, Really [ ] Solutions, uses the DITA solution for practice test books for each states – remapped element names to new element names and he gets all the SCORM online assessments pretty much for free because he’s using DITA. Nice.

Here’s my interview for GirlStart, highlighting a technical communication career for the “Check her out!” section of their website. The toughest question for me was the last one! GirlStart is a non-profit based in Austin that empowers girls in math, science, and technology. I was pleased to be able to say what a great career information development is, and also reading the other interviews was an inspiration to me!
So, here goes.

Title:
Senior Technical Writer, blogger
Company:
Advanced Solutions International and JustWriteClick.com

What do you do and what are some of your job responsibilities?

I write online help, website information, and user manuals for software that people use to run associations, non-profit organizations, and faith-based organizations. Our software can conquer mailings, large events, fundraising, organize and retrieve member contact information, and handle magazine subscriptions just to name a few tasks that large organizations do for their members.

I have to learn new features of a product quickly, and analyze the tasks that our typical users want to accomplish with our software product. Technical writers are sometimes described as extremely fast learners who can also interview to get the information they need as well as a journalist. My job involves writing, interviewing, learning about users, checking the software for quality, helping improve the user experience with the product, and constantly checking the future horizon to ensure our deliverables match what our customers want.

I also write a blog about information development and design at Justwriteclick.com, and it has helped me learn so much and connect and collaborate with others in my chosen field. I started blogging for my former employer, BMC Software, and it opened doors and opportunity to me because it moved me to the edges of my comfort zones.

How did you find your current job?

I belong to a professional organization called the Society for Technical Communication, and networking through those affiliations has helped me find every single career-type job I’ve found so far. Professional networking and social networking are huge parts of job-hunting, especially for fulfilling, flexible work like the jobs I have found a passion for.

Did you learn any of your skills from school?

I’m a little unusual in that my path to technical writer started with an undergraduate degree in chemistry, where I learned a lot about scientific thinking and process. After reading the manuals in the analytic laboratory where I worked for a summer testing powder samples of infant formula, I decided to explore how those manuals were written. I discovered a master’s degree program in scientific and technical communication and learned a lot of my specific job and career skills there, but I have also had to continually educate myself and reach out to others to learn more skills, for both technical and design-oriented skills. I also read a lot – books or blogs, either one is highly useful and helpful to me. I attend presentations, conferences, and training classes as well.

What would you tell a girl that was interested in doing what you do?

Technical writing and information design are professions that a lot of women have found to be fulfilling and interesting, and for many reasons, women are prevalent in the profession. I’d encourage you to read as much as you can and practice writing because both are important skills for writing technical information. I also would encourage a sense of excitement and exploration with technology, whether it’s Webkins or a Nike+iPod running sensor.

What are some of your hobbies?

I enjoy running very much and while I’m not fast, I am consistent. I’m into running for the long term ever since I found the best running partner in a friend 30 years older than me. I also write for my blog as a hobby and explore the latest technology in social media and computers by talking to my friends and colleagues online. I read voraciously and have joined at least three book clubs in the last few years. I also enjoy kids and especially my own kids. I teach my son’s classes as often as they let me and love going on field trips, even if they’re just in the backyard with a flashlight or binoculars at night.

What is your favorite website?

My favorite website is bloglines.com because that’s where I store all my blog feeds to read, and reading is my absolute favorite pastime. Probably my favorite website to visit is dooce.com because she’s an excellent writer and her daughter and my firstborn son are nearly the same age, so much of what she writes about I’m living. Right now, I enjoy del.icio.us/annegentle because it’s where I’m bookmarking all my favorite places to read and savor later. To talk with friends and coworkers, I enjoy twitter.com and twemes.com.

If you could talk to you when you were 12 years old, what advice would you give yourself?

This is a tough question, I have to say. Don’t argue with others for the sport of it comes to mind first, because my wise sixth grade teacher wrote that in my yearbook. Secondly, you’re not fat! Looks don’t matter as much as you think, but perceptions of presence, actions, and words (written and spoken) do matter. Learn as much as you can from those more experienced than you, and learn how to listen really, really well.

I have been talking to SJ Klein regularly via email and phone for my work on the wiki pages and kid’s user manual for the XO laptop for One Laptop Per Child, so I was excited to hear him speak and meet him in person. Also, directly afterwards I planned to go to lunch with SJ and with Robert Nagle, the technical writer (and self-named idiot programmer) in Houston who originated the idea of XO user groups across the states after the Give 1 Get 1 program completed.

I had tried my best to promote an XO meetup as a lunch after the Textbooks talk, even getting it listed on the entirely awesome sched.org, but when the four of us arrived at Las Manitas at about 10 after 1, we were the only ones with the “little computers,” as my son calls them. So we just waited our turn for seating, and got to know SJ and Melissa Hagemann, a program manager with the Open Society Initiative who was moderator for the panel. As it turned out, she and Robert had been in some of the same cities in south eastern Europe in the 90s. While speaking of books, Robert described hand-carrying two fifty-pound bags of books along dirt roads as a Peace Corp volunteer and for me it really brought home the fact that books – they are heavy. Much heavier than the two 3-pound XO laptops I had been “lugging” around the Austin Convention Center all day. The 3-pound OLPC library on the XO laptop probably contains hundreds of pounds of books, and you could add several hundred more pounds of books by putting in a small USB stick or SD card. Quite a revelation for me.

Here are my rough notes from the Textbooks of the Future: Free & Collaborative talk at SXSW Interactive 2008. I’ll link to the podcast of it when it’s available. (Updated to add the link, since now it is.)

For open source textbooks, take a look at cnx.org.

Yes, wikibooks are now possible. Pedia press had been doing high quality book output for a while, now partnering with Wikimedia Foundation.

OLPC’s interest in open education materials is that it gives students and teachers ability to share and collaborate on materials. They’re in a unique position in some ways, though, because they’d like to target 15 languages for their materials.

Why are open textbooks possible now?

• Convergence of technology and community
• Also XML – lets you build lego blogs of reconfigurable, recombinable objects (sounds like DITA topics, doesn’t it?)
• Online lets you go past books
• Intellectual property now has new licensing – creative commons license
• Development of quality control mechanisms, repository of content
• Lens – gives you a filter, lets you see things through a lens, filtering which items which you think are valuable
• National Instruments, Texas Instruments, checking the books, offering lenses

Print on demand options – if you can’t produce shiny books, you aren’t taken seriously in many parts of the world, and in some age groups, print is important. With just-in-time printing, books are assembled automatically, index generated automatically, print on demand only costs students $20 instead of $120.

The same thing will happen everywhere that knowledge is valuable.

Is there a role for publishers in the new learning environment? There can be conflicts even in branches of publishing. All major publishers he’s talked to know that a change has to happen. They’re investing/investigating.

What strategies are useful? “The Budapest Open Access Initiative: an international effort to make research articles in all academic fields freely available on the internet.” from http://www.soros.org/openaccess/index.shtml

Three dimensions -
people (blurring the lines of roles, in today’s society we have rigid lines of roles of teacher, or author)
networking, transmitters, guides

Q: Robert’s question as a representative from Teleread.org – people searching for tutorials or text books want “the best” – what’s the finished state?
A: People looking for most efficient and effective way to learn things. Those sites will rise to the top.

Q: Can you use a lens that is another company’s lens?
A: Next version, yes you can.

Q: What about “controversial” areas or areas that evolve year over year?
A: For CXN.org, they decided not to develop with a wiki model, allowing for a multiple entry model, such as causes for the civil war has multiple articles with author attribution. Lenses can then point towards most used, or most heavily peer reviewed, your choice.

Q: From instructional designer in corp. environment – she sees missing things such as visual representations or animations, what’s happening or needs to happen to bring in those valuable designers.
A: Inkscape – open source vector drawing application, access to others’ illustrations (svg, vector graphics standards) Also mentioned the payment for illustration contribution based on Phillip Greenspun’s donation to Wikimedia Foundation.

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.

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.

Lisa Dyer and Alan Porter presented at last week’s DITA Central Texas User Group meeting, and both told tales of end-user doc written and sourced in DITA, with wikitext in mind as an output. About 20 people attended and we all enjoyed the show. I wanted to post my notes to follow up, and I’ll post a link to slide shows as well.

This post covers Lisa Dyer’s presentation on a wiki sourced with DITA topics. I’ll write another post to cover Alan’s presentation.

Although, actually, first, Bob Beims shared Meet Charlie, a description of Enterprise 2.0. Seems very appropriate for the discussions we’ve had at recent Central Texas DITA User Group meetings talking about wikis and RSS subscriptions and web-based documentation.

Lisa has made her presentation available online. My notes are below the slideshow.

DITA source to wiki output case study

Lisa Dyer walked us through her DITA to wiki project. Their high level vision and business goals merged with a wiki as one solution, and Lombardi has customers who had requested a wiki. Lombardi’s wiki is available to customers that have a support login, so I won’t link to it, but she was able to demo the system they’ve had in place since July 2007.

What wiki toolset – open source or entprise wiki engine?

On the question of choosing an open source or enterprise wiki engine, Lisa said to ask questions while evaluating, such as where do you want the intellectual property to develop? Will you pay for support? Who are your key resources internally, and do you need to supplement resources with external help? They found it faster to get up and running and supported with an enterprise engine and chose Confluence, but she also noted that you “vote” for updates and enhancements with dollars rather than, say, community influence. (Editorial note – I’m opining on whether you get updates to open source wiki engines through community influence. I’m certain you can pay for support and enhancements to open source efforts with dollars.)

Run a pilot wiki project

She recommends a pilot wiki, internal only at first, to ferret problems out while building in time to fix the problems. While Michele Guthrie from Cisco couldn’t present on the panel at the last minute, she also has found that internal-only wikis helped them understand the best practices for wiki documentation.

Meet customer needs – or decipher what they want and need

Lisa said that customers wanted immediate updates, knowledge of what’s new with the product and doc (800 pages worth), and wanted to tell others what they had learned. She found that all of these customer requests could be met with a wiki engine – RSS feeds, immediate updates, and the ability to share lessons learned. At her workplace, customers work extensively with the services people and document the implementation specifically, and that information could be scrubbed of customer-specific info. They found that rating and voting features give good content more exposure. Also, by putting the information into wikis, they found that there were fewer “I can’t find this information” complaints.

Intelligent wiki definition and separate audiences for each wiki

They have two wikis – one is for end-user documentation, one is for Services information. In the screens she showed us, Wiki was the tab label for the Services wiki, Documentation was the tab label for the doc wiki. The Documentation wiki does not allow anyone but the technical writers to edit content, but people can comment on the content and attach their own documents or images. The Services wiki allows for edits, comments, and attachments. The customers and services people wanted a way to share their unsanctioned knowledge such as samples, tips, and tricks, and the wiki lets them do that. The Services wiki has all the necessary disclaimers of a community-based wiki, such as “use this info at your own risk” type of disclaimers. Edited to add: The search feature lets users search both wikis, though.

Getting DITA to talk wiki

There are definite rules they’ve had to follow to get DITA to “talk wiki” and to ensure that Confluence knows what the intent is for the DITA content. For one, when they want to use different commands for UNIX and Windows steps in an installation or configuration task, they would use ditaval metadata around in the command line text (using the “platform” property) and use conditional processing for that topic. However, because of the Confluence engine’s limitation of one unique name for each wiki article, they had to create separate Spaces for each condition of the deliverable (UNIX Admin guide or Windows Admin guide, for example). This limit results in something like 12 Spaces, but considering it’s output for several books for separate platforms, 32 individual books in all, that number of Spaces didn’t seem daunting to me. She uses a set of properties files during the build process to tell Confluence what file set to use, and what ditavals they’re seeking, and then passes the properties to the ant build task. The additional wiki Spaces does mean that your URLs aren’t as simple as they could be – but in my estimation, they’re not completely awful either.

While I was researching this blog post further, Lisa also added these details about the Spaces and their individual SKU’s (Stock Keeping Unit, or individual deliverable). “Building on this baseline set of spaces, each new SKU would add 1 to 7 spaces hosting 3 to 21 deliverables, depending on the complexity of the ditaval rules and the product. Obviously, the long pole in this system is ditaval. A more ideal implementation would probably be to render the correct content based on user preferences (or some other mechanism to pass the user’s context to the engine for runtime rendition). Or, a ditaslice approach where you describe what you need, and the ditaslice is presented with the right content. Certainly innovation to be done there.”

Creating a wiki table of contents from a DITA map

She creates a static view of the TOC from the DITA map as the “home page” of the wiki. She currently uses the Sort ID assignment a DITA map XSLT transform to generate the TOC. She said they implemented a dynamic TOC based on the logical order of the ditamap by dynamically adding a piece of metadata to each topic – a sort id using a {set-sort-id} Confluence macro. The IDs are used to populate a page tree macro (the engine involved is Direct Web Remoting, or DWR… an Ajax technology). Currently, their dynamic TOC is broken due to a DWR engine conflict, which should be fixed in the next release. In the meantime, they are auto-generating a more static but fully hyperlinked TOC page on the home page of each Space. A functional solution, not great for back and forth navigation, but it shows the logical order which is pretty critical for a decent starting point.

DITA conref element becoming a transcluded wiki article

Another innovation she wanted to demonstrate was the use of DITA conrefs output as translusions in the Confluence wiki engine, so that in the wiki, the transcluded content can’t be edited inside of an article that transcludes the content. I don’t think it quite behaved the way she wanted it to, but knowing it’s a possibility is exciting. Edited to add: This innovation really does work, Lisa simply was looking at the wrong content (she admits, red-faced.)

Burst the enthusiasm bubble, there are limitations and considerations

One limitation that I observed is that when you transform the DITA source to Confluence wikitext, there are macros embedded, so when someone clicks the edit tab in the wiki, they must edit in wikitext, not the rich-text editor, to make sure the macros are preserved. In the case of the Documentation wiki, they can instruct their writers to always use the wikitext editor. But, for the Services wiki, one attendee asked if users prefer the wikitext editor, and Lisa believes they do. Someone running MoinMoin at their office said they finally just disabled the rich text editor because they didn’t want to risk losing the “cool” things that they could do with wiki text. The problem at the heart of this issue is that if users really like the wikitext editor and do a lot of “fancy” wiki text markup (like macros), then another wiki user using the rich-text editor can break the macros by saving over in rich text. Edited to add: Lisa wrote me with these additional details which are very helpful – “actually, the macros are preserved when in Rich Text Editor (RTE) mode. the problem is that it looks ugly as heck – and if the user is not techie, potentially confusing. the RTE does add all kinds of espace characters to the content– in a seeming random way – and can negatively impact the formatting in general when viewing, but it doesn’t seem to affect our macros. However, if a user wants to use macros to spiffy up the content, then wiki markup mode is definitely recommended.”

If you’re interested in a copy of the case study, you can purchase it for $10 here:

White paper, Structured Wikis in Software Engineering

This white paper describes using Darwin Information Typing Architecture (DITA) and wiki collaborative authoring environments in concert to enable software development processes including Agile development.

$10