Monthly Archives: January 2008

wiki

What does DITA have to do with wiki?

We tackled this question and then some at the January Central Texas DITA User Group meeting. I’m a little tardy in writing up my notes and thoughts about the presentation but it went really well and I appreciate all the attendee’s participation as well. We had a high school teacher in the audience and I applaud him for wanting to learn more about DITA to pass that knowledge on to high school students.

I brought along my XO laptop since I was talking about my work with wiki.laptop.org and Floss Manuals and found some more Austin-based XO fans, so that was a great side benefit to me as well.

One of Ben’s answers to the question “What does DITA have to do with wiki?” is “Maybe nothing.” Love it!

Ben introduced another the triangle of choices – you have likely heard of “cheap/good/fast, pick two.” How about “knowledge/reuse/structure, pick one.”

I have to do some thinking about that one and his perception of the limitations and tradeoffs offered by those choices or priorities. Reuse and structure are particularly difficult to pair but also give you the most payoff. Structure and knowledge are another likely pair, but it could be difficult to find subject matter experts who are also able to organize their writing in a very structured manner, and finding writers who know DITA really well and also have specific content knowledge may also be difficult to obtain. His workaround for the difficulty you’d face while trying to come up with a structured wiki is a sluice box – where raw, unstructured data is the top input, some sort of raw wiki is the next filter, and the final tightest filter of all is a topic-oriented wiki.

Sluice box, by Tara, http://flickr.com/people/wheatland/
Original photo of a sluice box by t-dawg.

My take on the question is that there are three potential hybrid DITA wiki combinations, and Chris Almond at this presentation introduced the fourth that I have seen, using DITA as an intermediate storage device, interestingly.

The three DITA-wiki combination concepts I’ve seen are:

  • Wikislices – using a DITA map to keep up with wiki “topic” (article) changes. Michael Priestly is working on this for the One Laptop Per Child Project (OLPC.)
  • DITA Storm – web-enabled DITA editor, but not very wiki-like. However, with just the addition of a History/Revision and Discussion tab, and an RSS feed, you could get some nice wiki features going with that product. Don Day had an interesting observation that sometimes when you add in too many wiki features on a web page you can hardly tell what’s content and where to edit it. I’d agree with that assessment.
  • DITA to wikitext XSLT transform- but no round trip, have writers determine what content goes back to DITA source. Lisa Dyer will describe this content flow in the February session.

The slides are available on slideshare.net. Here are the slides that Ben Allums, Ragan Haggard, and I used.

Here are Chris Almond’s slides and his blog entry about the presentation. I described Chris’s project to Stewart Mader of wikipatterns.com and he blogged about our presentation as well at his blog ikiw.org.

tools work

Adding Google Analytics to your Author-it generated HTML pages

I’m learning about Author-it’s HTML templates today, and how to insert Google Analytics code (or any other code, really, such as adding an automatically updating variable for “Last modified by” with user or date information.)

But my task today was to insert Google Analytics code. (As a prerequisite note, we already have all our documentation available on an external site at docs.imis.com.)

First, I created a Gmail account for our department. Next, I created a Google account. Then, I went to the Google Analytics page and signed up for an account there, entering the name of our externally-accessible documentation site.

At the end of the sign up process, Google gives you javascript code that you want to place directly above the closing body tag </body>. Fortunately, the way that Author-it sets up the HTML templates, all of your Author-it topic data is inserted at a point where the <aitdata> tag appears in your HTML template.

The HTML templates are typically stored in C:\Program Files\AuthorIT V4\Data\Templates\Plain HTML, although other types of HTML templates such as DHTML and HTML Help templates are also available. These are the files I discovered that Google Analytics needed to be installed on.

  • I edited the body_template.htm file and located the <aitdata> tag. I copied the code from the Google Analytics page and pasted it below the <aitdata> tag.
  • I edited the html_frameset.htm file and added the Google Analytics code in the <head> area as instructed by the Google Analytics help, which, as a side note, has a set of completely question-based articles, as in, all headings are written as a question. Fascinating. The topic is “What should I know about using Analytics with Framed sites?

Now, republish the HTML from your Author-it topics and your Google Analytics code is available on each page. After about 24 hours we started collecting data.

google_analytics.jpg

Let me know your experiences using Google Analytics to monitor your user assistance site traffic – what metrics are you seeking? Are there any conversion goals we should set up? One metric I am considering is trying to monitor how often the Word .doc files are downloaded. Does anyone have tips or tricks for us?

Update: I found this blog entry, Tracking document downloads in Google Analytics, and it contains hints at what I need to do to track our Word document downloads. However, I think that this article from the Google Analytics Help, How do I track files (PDF, AVI, or WMV) that are downloaded from my site? contains the method I’ll try first.

OLPC

How to download and copy epub files using the XO laptop

Bob DuCharme recently converted 16 children’s books from the Project Gutenberg archive into .epub format for use with FBReader on the XO laptop. Thanks Bob!

I’ve just walked through the scenario of downloading the epub files from Bob’s download page and copying them into the correct directory for FBReader to read them. Here are the instructions with screenshots taken directly from the XO. If you see inefficiencies, please let me know because my Linux is only good enough to make me very, very dangerous to files and folders. :)

  1. Start up the Browse Activity on the XO.
    browse.png
  2. Click in the address bar and press ctrl-A to select all the text, then type in snee.com/epubkidsbooks and press enter.
  3. Scroll down to the book you want to download, and click the link. You’ll see a nice countdown while the file downloads.
    sneecom.png
  4. Switch over to the Journal Activity, either by pressing the magnifying glass icon key or by going to the Home View and clicking the Journal icon at the bottom of the Home circle.
  5. Insert an SD card or a USB stick into the XO. The Journal shows an icon in a bottom bar when you put in external storage media.
  6. Locate the downloaded epub file, but don’t launch it (they launch as EToys projects, go figure.) Drag and drop the file to the SD or USB icon in the bottom bar.
    filelittlebopeep.png
  7. Click the Home View key and start the Terminal Activity – you have to scroll right to see the Terminal launch icon.
  8. Click in the Terminal window (otherwise you’ll be typing in the Terminal search box). Find the name of the external media, which is in the /media directory. For example, type:
    df
  9. You’ll see the name of your SD card or USB stick in the row with /media/ before it. You need that name to copy the epub file from the external media to the correct location for FBReader to find the book file.
    terminalmvfile.png
  10. Change to the media directory where the epub file is stored and rename the file to something shorter. For example, type:
    cd /media/USBMEM
    mv "File TheThreeBears.epub downloaded from_http___www.snee.com_ebooks_TheThreeBears.epub..zip" TheThreeBears.epub LittleBoPeep-ANurseryRhymePictureBook.epub
  11. Copy the newly shortened-name file to the ~Books directory. For example, type:
    cp TheThreeBears.epub ~/Books
  12. Launch FBReader by typing FBReader at the Terminal prompt.
    thethreebearsinfbreader.png

Tips:

  • FBReader must be installed on the XO. It’s a simple process. Go to the Terminal Activity and type:
    su -c ‘rpm -i http://mirrors.kernel.org/fedora/updates/7/i386/fbreader-0.8.8-2.fc7.i386.rpm’
  • If you don’t want to type a whole bunch of text on the little XO keyboard, eject the SD card or pull out the USB stick, and put it in a “regular-sized” computer, and then rename the file there.
  • Or, plug in a USB keyboard with normal size key layout to do all your typing in the Terminal Activity.
  • If your USB stick has a space in the name, you can’t use it with your XO. Put it into another computer and rename it without a space.
writing

Two panels on wikis and structured authoring such as DITA

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.

The February panel has some experience implementing a wiki framework for DITA and also single sourcing wikis – so they can offer a from-the-trenches look at the building blocks (transforms, feature and process requirements, lessons learned from running the project).

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.

OLPC

Austin, Texas – XO on the menu for lunch

XO Austin

Our three XOs in a row

We got the two other XO buyers that I know of in Austin for lunch last week – buyers of the One Laptop Per Child computer, called the XO laptop. Whurley and Mikus and I met at Berryhill Baja Grill, where indeed, wireless access was present. My XO was able to connect, but for some reason Whurley’s did not. And Mikus had hacked his network configuration to use a USB-Ethernet adapter cable, so his wireless wasn’t working. We thought that Whurley’s machine would be able to “mesh” with mine to get a connection, but that wasn’t the case. Even in the Group View I couldn’t see the other XOs sitting right next to me. Pout.

Still, we got to compare colors (look at the variety!), try out the Distance Activity (it didn’t work, and it’s not acoustic, we are not fooled), and Meebo worked like a charm on my XO. So all in all, a fun time! I think one of the Linux Austin groups got their XOs together recently, and we’re going to try to get together again, so stay tuned. Rumor has it that 30 XOs were purchased in the Austin area, so hopefully we can get them together and see what we can do.

I’ll report more later this week when I show Turtle Art and Tam Tam Jam to the four-year-olds in my son’s preschool class. Wish me luck giving a demo to a bunch of four-year-olds!

Wikipatterns, the wiki, the book, teh awesome

I’ve gotten a review copy of WikiPatterns (the book) in the mail and I want to review it here and make sure everyone who reads my blog knows about this book and the WikiPatterns website. It’s a guide to getting the most out of your wiki and the most from collaboration with the people you work with via a wiki. Combined they offer such a great resource.

I admit, I read the Questions and Answers first, even though it’s near the end of the book. I guess I wanted to see how Stewart would answer the questions I hear from others. I enjoyed his answers and comparing them to how I’d answer. I think I’m in agreement with him 100%.

Next I went through choice Case Studies, starting with Leap Frog. There are loads of case studies and they involve internal and external wikis. One thing I noticed while reading the case studies is that the case studies refer to the patterns and anti-patterns by name, so you must refer to the wikipatterns.com website to study up on ‘em to get the most out of the book. You should refer to it regardless of your use of this book, it’s just that good.

Lots of fascinating tidbits in the case studies, though. I didn’t know that Leap Frog was an Agile development environment. Their internal wiki is named “Emma” which is cute to me, and apparently was better than naming it a wiki project. Good pointer.

Next I read about the author. Turns out, Stewart Mader and I both have Chemistry degrees.

Which led me to the foreward. Ward Cunningham, the inventor of the wiki, wrote an excellent foreward that will inspire you to become an activist, wiki-based or otherwise. And he reminds us that we humans crave collaboration.

Then, I boggled at an entire chapter dedicated to proving that Wikipedia’s perceived “problems” will not transfer directly to your wiki implementation. Thank you! Thank you! I’m not alone in trying to go against the anti-Wikipedia sentiment applied to other wikis especially for technical documentation such as end-user manuals.

Next, I moved on to the examples of wikis in use. Wow, wiki as peer directory. This is an excellent use that I wouldn’t have thought of until it was spelled out for me in this book. Collaboration works best when you know the person. And knowing the person in a global company often means only finding out about them through their profile page. At BMC, we used editable Sharepoint pages to upload pictures for remote stateside team members and writers based in India, which helped us get to know each other better on a personal level. It makes it all the easier to ask about the weather or a certain family vacation before diving headlong into some technical topic or project hurdle with a team mate.

Also, wiki as meeting agenda opener-upper. I loved adding agenda items to a Sharepoint site when I thought of them, rather than trying to remember them and send them in an email to the right person before a meeting started. That’s exactly what goes on a wiki. Things that you don’t want to trap inside of an email, nor do you have to wait until an email is sent out requesting agenda items.

So there you have it – my review of an excellent book that is a carry-around edition of the wiki with the same name. While it works well with the wiki, it offers more than the wiki alone contains.

techpubs wiki

Specialized information hoarding

I get the greatest blog ideas from my lunch companions lately. This week it was a few former BMC writers. At BMC, the writers have an annual book exchange around the holiday time, and it was so popular we sometimes repeat it mid-year.

At our book exchange, everyone would bring a wrapped book, place it in a pile, then draw a number out of the hat. The person who drew the lowest number would chose from the pile, unwrap the book, read the description, and then the person with the next number would choose to either “steal” the already unwrapped book or take from the pile. The person who drew the highest number would have many unwrapped book titles to choose from.

For a few exchanges in a row, Jonathon Strange & Mr Norrell appeared in the book exchange pile, so all four of us at this lunch had read and enjoyed the book very much.

Could you hoard all the information on a topic if you wanted to?

uspbkjacket_w150.jpgJonathon Strange & Mr Norrell is a wonderful fantastical story about the return of magic to England due to the two people in the title (well, and due to other forces). There are humourous parts, and the fun of the book is that each magician has a very different approach to learning magic again. One hoards all the books about magic. ALL the books. This aspect of information hoarding was especially interesting to us writers at our lunch discussion. Could you even do that in modern day – collect all the books about a certain topic (albeit a narrow focus?) No way.

Another observation is that the cautious one is the one who hoards all the information and only very reluctantly shares it with his reckless pupil. I’m working on a panel discussion on collaboration and I can’t help but remember this book and how fruitless and unsuccessful it was for Mr Norrell to attempt to keep all the books on magic in a single library. The similarity I would draw is how difficult and unhelpful it is to try to write all the information and hoard your topics, never to be remixed into other deliverables.

If the information is hoarded, how is it released to the wild?

Another story that came up in the same week of lunchtime conversations was one from Don Day. He has had a certain camera since he was in high school, and never knew that much about it. He has taken it apart numerous times, and looked for books about the camera, searched on the web with all the identifying text he could find inside the camera, and tried to find any additional information about it, but never found out more.

But! This past year, when someone (I believe the book’s author) uploaded several chapters from a book about specialized vintage cameras to the Internet and it became indexed by Google, Don learned that his old camera that he couldn’t previously identify is worth a couple thousand dollars! It was like the TV show, Antiques Roadshow, had delivered an appraiser to Don through the Internet.

Don’s love of cameras comes full circle in the information sharing sense. Don maintains a wiki about cameras called “Light of Day” and has wonderful photos there. I like this quote from Don’s bio in a wiki entry about the Central Texas DITA User’s Group meeting for October. “I work in high tech, but I love simple things, which is why I feel that an early camera, made of leather and wood, but fitted with a precisely-polished lens, is such a great complement to my own life experience.”

With these two tales of information collection, I hope you see the beauty of share and share alike. Any one else have a great story of information suddenly revealing itself? Or a tale of an information hoarder who met with trouble?

Look out, updated headshots are coming

The headshots I’ve been using (including the one that stays on my blog at talk.bmc.com) were taken by my husband one morning before work. In fact, my son is on my lap in one of the ones that didn’t make it to the “released” state. :)

Since those were a few years old, I decided it was time to update my headshots. So I asked my photographer friend Beverly Demafiles to come over to the house one late afternoon this fall for some professional shots. And wow, did she deliver the goods! I highly recommend her services if you’re looking for professional portraits or for wedding photography. She’s here in Austin and does spectacular work.

Beverly Demafiles photography logo

As a blogger, I’ve found it important to ensure that people know there’s a real person behind the writing. By offering updated photos I think I can continue to ensure that you know it’s really me. Plus, with some of these perspective portraits, you can know that I’m pretty short, really. My friends mostly think I’m taller than I am, though. I guess I must “stand tall.” :)

A few years ago, I accidentally painted our house pink. Pepto pink in fact. I have since vowed to buy quarts or pints of paint and try out colors on the side of the house so the neighbors can vote before any paint is applied in earnest.

pepto pink house

So, in the spirit of trying out portraits before plastering them everywhere, which portrait do you like best? Your vote matters so let me know which ones you like best by leaving a comment with the number.

  1. anne_001_small.jpg
  2. anne_002_small.jpg
  3. anne_003_smal.jpg
  4. anne_004_small.jpg
  5. anne_005_small.jpg
  6. anne_007_small.jpg
  7. anne_009_small.jpg