Monthly Archives: December 2007

wiki

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

XO Quick Start

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.)olpc_letter.jpg

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

wiki

WikiMedia wiki text – best formatting for step-by-step instructions with graphics for each step?

Getting into the trenches of wiki editing has certainly taught me a lot. My learning has mostly been by trial and error and experimentation. I’m playing around with the best way to use Wikimedia wikitext for step-by-step instructions with graphics for each step. (And wishing that Wikimedia was just HTML based, I know the rules there.)

I’m learning a couple of things. One is, add in any new line and the wiki thinks you’re starting over your numbered list. For example, I was trying to do a numbered list with graphics after each number.

Doesn’t look like I expected

# From the Home view, launch Browse.
[[Image:Launchbrowse.jpg|none|thumb|150px|Browse Activity]]
# Type wiki.laptop.org/go/Activities and press Enter.
[[Image:Browsegoactivities.jpg|none|thumb|150px]]

This wikitext gave me 1. first step blah blah blah followed by 1. second step blah blah blah. Woops! Not what I wanted. So instead, I put a space instead of a new line.

Works like I was going for

# From the Home view, launch Browse.[[Image:Launchbrowse.jpg|none|thumb|150px|Browse Activity]]
# Type wiki.laptop.org/go/Activities and press Enter.[[Image:Browsegoactivities.jpg|none|thumb|150px]]

This wikitext gave me 1. first step 2. second step.

Now what to do

But then I tried to get fancy with the <gallery> tag to combine graphics for one of the steps. That restarted my numbered list at 1 after the gallery tag.

<gallery caption="Downloading an .xo file">Image:Jigsawxo.jpg|First click the link on the Activities page
Image:Versjigsawxo.jpg|Then click the link on the resulting page</gallery>

Numbering restarts at 1 after 4

I’m feeling a little lazy so I won’t research very far. The Extended image syntax page on Wikipedia had the most detail that I’ve found so far. I’ll probably just put the second XO download screenshot on the same line as the other so that the list numbering will work. Or try it for yourself at the OLPC Simplified User Guide, Installing New Activities section.

tools

Secrets of altering Altoid tins

I’ve been doing quite a few photo projects lately, but mostly with digital items. I did my family photo card this year with a Photoshop layout similar to the ones on purplestork.com, for example. The digital environment is fun, but I still enjoy the paper arts as well, scrapbooking, stamping, and card making, and I generally love altered ordinary items.

This post shows my first attempt at altering Altoid tins. I’m putting miniature scrapbooks inside of the Altoid tins for some friends and family members this year. Hopefully they’re not reading this blog post before they get their gift!

Photo collage of altered Altoid tins

For me, the secrets are in getting the dimensions of the rectangles for the top, bottom, and insides of the tin. I say it’s 2.25″ by 3.5″ but you have an extra eighth of an inch to work with on the longer side.

I cut paper rectangles 2 1/8th inch by 3 1/2 inch, and then used a corner rounder I bought for $8 at Michael’s. A 3 7/8th inch long side also works if you want to cover more but you have to glue precisely.

For some of the tins, I cut a 1/2 inch by 12 inch strip of paper to cover the side, although you could use 11 inch paper length and still get all the way around the tin. Ribbon also works well, so I used that for some of the circumferences of the tins.

With my foam brush I put a thin layer of Mod Podge on the tin and put the paper rectangles on, then smoothed out any air bubbles. I didn’t need to do anything to the tin itself except for wash it out, no sanding required.

I bought the tins from an Austinite on Craiglist – over 30 tins for $3. I had all the supplies in my growing scrapbooking and stamping collection except for that corner rounder.

And if all those supplies are not around your house but you want to get your hands on some altered Altoid tins, pop over to Etsy.com. Those designs blow mine out of the water!

wiki

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. riverbend.jpg

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?

tools

Ebooks showdown Kindle vs. XO laptop from OLPC

I’m learning more about ebooks thanks to some recent inquiries related to my work for One Laptop Per Child (OLPC) to collaborate on the kid’s user guide. I’ve been so busy with that I’ve barely had time to blog. I’m learning so much it’ll add to the blog entries later.

But I have been noodling on the fact that Amazon’s Kindle and the OLPC XO are at the exact same price – $400 – and that the XO can be used as an ebook reader (PDFs preferred.)

I’m going to try to do a comparison here, but please realize I’m no ebook reader expert nor have I owned one in the past. So I really have no business writing this at all other than my innate curiousity and love of researching and then presenting information.

On to the interesting comparison – let’s look at other parameters, and feel free to suggest your own. Like I say, I have no business writing an ebook comparison so do pitch in where you see fit.

Amazon’s Kindle ebook reader versus the One Laptop Per Child XO in ebook mode

Comparison item Kindle XO
Dimensions kindleebook.jpg7.5″ x 5.3″ x 0.7″, weighs 10.3 ounces xoebook.jpg9.5″ x 9.0″ x 1.25″, weighs about 3 pounds
Price $400, free shipping $400, about $25 shipping, $200 is a tax-deductible donation, so slight discount depending on your US tax bracket, I suppose
Content DRM content, can’t read PDFs unless you have a Windows PC and convert them first. Mostly PDF, but plans for more format support. With the built-in browser (Browse Activity), many reading materials are available such as Project Gutenberg.
Usability Robert Scoble has a harsh usability review of the Kindle. Robert Nagle I hope will review it in the future, but he has a great review of the possibilities as an ebook reader for kids. And I like the review written by a 12 year old.
Battery 30 hours 4-5 hours
Wireless connectivity Uses a wireless cellular network it calls Whispernet to deliver your Kindle content. It’s EVDO. Uses 802.11b and comes with a free one-year subscription to T-Mobile wireless service.
Screen monochrome: 600 x 800 pixels (167 dots per inch) monochrome: 1200 x 900 pixels (200 dots per inch), color: 1024×768 perceived (it’s complicated, see the hardware specs PDF.)
Warranty one year 30 days

Gizmodo already put the Kindle up against the Sony Reader in this online poll. I realize that the OLPC XO is intended to be a kids laptop, and it’s not really fair to pit it against the Kindle because that’s not the design of the device (nor the intentions of the project behind the device.) But your $400 might be well spent here.

By the way, I read about expected XO delivery information from the new XO User’s Facebook Group 50 members and growing. If you order now, you’ll get your laptop arund the same time as a child in Afghanistan, Cambodia, Haiti, Mongolia or Rwanda – in early 2008. See Shipping information on laptop.org.

Saturday extra – Christmas spirit in Austin, Texas

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!)

elfsegway.jpg

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.

tools

Author-it and converting UTF-16 to UTF-8

In trying to modify multiple Author-it topics (okay, 5,119 topics) with variable assignments, I have had to work with the XML output that Author-it exports.

To export to XML, you select a topic or multi-select topics, then right-click on the selection and choose XML > Save to file.

Turns out, Author-it outputs its XML encoded with UTF-16, but apparently most Windows applications understand UTF-8. When I tried to open my freshly export XML file, XML Copy Editor gave me an error.

So I had to discover how to convert the XML from UTF-16 encoding to UTF-8 (and you can’t just open it in Notepad on Windows and change the 16 to 8, there are other embedded characters indicating the encoding, and, well, it’s encoded.)

First, I used the identity transform documented many places, my favorite place being the XSLT Cookbook, to convert the Author-it output to UTF-8. Here’s the XSLT code for that:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:output encoding="utf-8"/> <xsl:template match="@*|node()">

	<xsl:copy>	 	<xsl:apply-templates select="@*|node()"/>

	</xsl:copy> </xsl:template>

</xsl:stylesheet>

I just ran the above transform against the AuthorIT Objects.xml file I exported, using the Instant Saxon XSLT processor.

Then, I wanted to remove all <VariableAssigments> elements, effectively removing an entire node. Again, the identity transform (or copy transform) was effective. And, I learned that I had to identify the AuthorIT namespace thanks to this excellent helper article, Handling Default Namespaces on topxml.com.

<?xml version="1.0" encoding="UTF-8"?>

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"

xmlns:ait ="http://www.authorit.com/xml/authorit">

<!--Match everything using identity copy-->

<xsl:template match="@*|node()">

	<xsl:copy>

	<xsl:apply-templates select="@*|node()"/>

	</xsl:copy>

</xsl:template>

<!--Remove all the VariableAssignment nodes-->

<xsl:template match="ait:VariableAssignment">

	<xsl:comment>Removed VariableAssignment element</xsl:comment>

</xsl:template>

</xsl:stylesheet>

This transform is pretty dangerous, though, because it’s taking away all the VariableAssignment elements, and you might have valuable metadata stored that you would quickly blow away. So use with care.

This workaround is likely also useful for DITA and XHTML files, because Author-it outputs its DITA and XHTML files as UTF-16. I haven’t investigated its usefulness for those areas, but a quick search on the Author-it-users group on Yahoo revealed that sometimes people want UTF-8 rather than UTF-16. So, I hope this helps.