XO doc and the journey to wiki-fied documentation

Just wanted to give another update on the happenings in the end-user doc front from my neck of the woods. (Idioms sprinkled throughout!)

I got an HTML copy to SJ and a second copy with an Index and some customizations on the CSS. I tested it on an XO emulation and the Browse Activity does really well with the Index and search so I’m pleased with the results.
http://www.mooseworld.org/olpc/index.htm

Here’s what it looks like when you view it on an XO in the Browse Activity (click on the image to see it full-sized).

I’ve written a letter of appreciation to Author-it for giving us the license and ability to do quick rearranging. It’s coming in handy.

Adam Hyde of FlossManuals.net and I met to talk about a migration path for the kids end-user doc content at http://wiki.laptop.org/go/Simplified_user_guide. They’ve just finished a lot of translation work so that we can also have multiple language versions of the simple user guide on the FM site and translators could work in a side-by-side view which is nice. The next steps are for me to re-arrange the content in Author-it into an outline closer to the structure that FM uses (Introduction, Installing, Interface, Tutorials, Appendices). Once I get the new structure to the content, Adam and I and anyone else who wants to pitch in can do copy and paste of the HTML into the FM pages. Adam’s filling out the infrastructure on FM now here:
http://en.flossmanuals.net/bin/view/OLPC_simple/WebHome

From Adam I learned that the formatting of the print versions out of the Floss Manuals wiki uses Scribus - http://www.scribus.net/. It’s an open source page layout and publishing tool.

Also, I have had a few people contact me this week to see how they can help so I’ve sent them the information about the different groups for the different user guides from the wiki.laptop.org/go/Manuals page. Here are the basics for how to help.

1. Join the Library list at http://lists.laptop.org/listinfo/library where documentation discussions occur.
2. Sign up for an OLPC wiki account at wiki.laptop.org.
3. Download and install an emulator. (optional, but helpful) QEMU is an open source processor emulator that can emulate an entire PC, including its peripheral devices like the disk, display, network, and so on. You must download and install this package to emulate the XO laptop.
4. Become familiar with the Simplified User Guide at http://wiki.laptop.org/go/Simplified_user_guide and read about the audiences at http://wiki.laptop.org/go/Manual.
5. Feel free to edit or start a new page with a new audience in mind. Note that we are porting the kids manual to Flossmanuals.net so also become familiar with their structure.

I’ve also started an Educator’s Guide at http://wiki.laptop.org/go/Educators_guide . I am way out of my league writing about constructivism and intervention guides (lesson plans) but I figure I have to start somewhere. I also want to link to as many additional reading materials about constructivism and how to teach with that learning theory in the forefront. There’s a nice post over at OLPC News that has great reading materials and ideas for accessories. I’ll also study the http://wiki.laptop.org/go/Educational_activity_ideas page as well.

I still have some edits that I need to do to the Simplified user guide wiki page, and I really want to re-write the interface instructions (or someone else could if they are feeling energetic.) I recently re-wrote the instructions for installing a new activity with screenshots from Update.1 for each. So I’m now able to run Update.1 in my emulation environment.

I’m also working with people who have worked on the artwork. There are some talented artists giving their time to the project.

The journey to Floss Manuals is going to be interesting for several reasons. One is, which wiki is source? Floss Manuals or wiki.laptop.org? Adam and I will likely have to get notifications on each wiki and attempt to keep them synced. I’m also trying to design for re-use because it’s easy to remix manuals in Floss Manuals. So there should be a way to use content from the simplifed user guide where kids are the audience for the teacher or instructor’s guide. The translation workflow in Floss Manuals lets the translator view both text side by side, which will be helpful I believe, but there’s no translation memory.

Another observation - my perception is that OLPC really wants the wiki.laptop.org to be the single place to get information. A recent status update encouraged the developers to make sure their Activity wiki pages are clean, neat, up-to-date, and accurate. However, there is a nice set of topics at laptop.org/start that the Give1Get1 participants are pointed to in the letter they receive when opening their XO laptop box. (Thanks to whurley for posting his xo unboxing photos on flickr.)

Since I think it is a good idea to have these separate pages, my perception is that there is definitely a limit to what the wiki can do for the general public (although I would qualify that statement by saying that most XO participants are not the general public.) The laptop.org/start pages are an excellent design and clearly written with an easy-to-use navigation system. I’d love to find out the page hits and find out if there’s any way to measure effectiveness of those pages versus the wiki pages (or the wiki as a whole).

Subscribe to the comments for this post

The Rockley Blog - wiki’s delivery mechanisms

I’m thoroughly enjoying the new Rockley Blog at http://rockley.com/blog/. I’m so glad Steve Manning and Ann Rockley are blogging, especially about wikis.

I appreciated Steve’s post “Wikis for Documentation” especially where he says that the delivery side is the weak point still. Agreed, but I have seen pockets of improvement there and need to be blogging heartily about them.

About three years ago I was equally as unconvinced of a wikis usefulness for end-user doc. An Agile-advocating developer mentioned the idea of using wikis so that the end-user doc could stay in sync with their fast Agile iterations. Yipes I thought! Wikis did work well for convincing the developers to contribute their knowledge, though, and internally they became a useful knowledge sharing (and finding) system.

Now I’m starting to see more and more actual customer need for them. I just had a great discussion about the difference between what a customer needs and what a customer thinks he or she wants, though, so some of what’s necessary is interpreting whether a wiki can fulfill a customer need. I got a small chuckle out of the title of this blog entry - Wikify Documentum Already - but he’s talking precisely about the gains you and your customers make when documentation is in a wiki. The interesting momentum going now is whether the current large enterprise content management systems can start to see the value in a wiki output, or whether the wiki engine providers themselves are going to catch up with the full feature set available in the large enterprise systems.

But wow, I’m learning how difficult wiki maintenance and trust patterns can be while using the wiki.laptop.org site to help out with their end-user doc. In some ways, wiki doc is more difficult than using the real CMS tools that we’ve become accustomed to (read: spoiled by). But I’m also learning how amazing the collaboration opportunities are when using a wiki. I’m still marveling at the communication going on in the discussion pages as well as the volunteer spirit that has come through a request on an art network.

So, what to do to get decent output for content delivery using the multiple channels that us advanced single-sourcers are already accustomed to? I’m planning to move the XO’s end-user doc towards the Flossmanuals.net model of a highly customized Twiki implementation where you can get and print a PDF from the wiki. I can’t wait to learn more and I’ll blog about it as I find out. It’s a step in that direction, though, where you deliver user guides and online help and web sites tailored to the needs of specific audiences. Language translations in a highly distributed environment are going to be an important part of the project, and I’m curious about how Flossmanuals provides for that aspect.

I’ve learned that you can write a Confluence plug-in that will take DITA source and turn it into wiki text. Confluence has PDF output capability as well, so it’s another step in the right direction to get that just-in-time content delivery that a customer needs (but doesn’t know that they want.)

Putting documentation in a wiki (or any really-well-indexed web location, really) can increase findability. If you get internal comments that say “you haven’t documented this particular feature enough” and you feel the feature is sufficiently documented, examine the findability of your documentation.

Also in our user advocacy role we are learning how to listen to customers and then interpret their needs. As information acquisition continues to gather speed, we not only provide the information but should also make informed choices about delivery methods.

Examples of what a customer wants but might not know that a wiki can deliver:

• What’s new with the product?
• How do I interact with documentation, support, the company represented as an actual live person?
• I want immediate information updates.
• I want to discuss the nuances of an implementation decision.
• I need to find others who are attempting what I am in the same type of field (insurance or banking).

What are your thoughts? Are we spoiled by our advanced delivery systems and waiting for wiki engines to catch up? Or are wiki authoring and delivery systems already giving us collaborative opportunities that are unparalleled?

Subscribe to the comments for this post