Monthly Archives: July 2008

blogging OLPC techpubs

BookSprint for Floss Manuals writing for the XO and Sugar

I’ve been busy lately working on plans for a Floss Manuals BookSprint. A BookSprint is a week-long concentrated effort of technical writers getting together to create a manual for free, libre open source software products. BookSprints are like a workshop where writers come together to learn how to write good user documentation. BookSprints are also a social experience where writers come together to form a community who share common goals and experiences.

Writers are giving a week’s time to be curators of information housed in wikis and websites everywhere, bringing it all together into the FLOSS Manual TWiki implementation to be ready for online viewing or gorgeous print output. If you’re interested in joining us for a day or all week, we’d love to have you. We’re planning to invite local students to the event also.

This picture shows the recent Inkscape BookSprint held in Paris France. We’re planning to hold the XO/Sugar BookSprint here in Austin, but I’m guessing the collection of laptops and cables will be the same here as there!

Inkscape BookSprint in Paris

Inkscape BookSprint in Paris

In this case, we’ll produce a comprehensive manual for the kids, families, and teachers using the little green XO laptop. While the manual that exists at flossmanuals.net/olpc_simple is a targeted effort, it is outdated for the new line drawn between hardware (XO) and operating system (Sugar). Our hope is to expand the manual in advance of the new expanded Give 1 Get 1 program will give educators and children a chance to learn about their laptop, repair it, program with it, and teach others.

What can you do to help? Right now, I’m raising money and asking for in-kind donations to help with this concentrated effort. Here are some ideas, although you can come up with creative ideas yourself if you want!

$500 would provide hotel accommodations for a writer
$250 would provide a catered lunch for all the writers
$100 would provide gas money for many writers all week

Updated to add: You can also directly give donations at http://en.flossmanuals.net/donate.

Sponsorship earns not only good “whuffie” but we’ll list your name or business name on these websites: FLOSS Manuals, JustWriteClick, Sugar Labs, and OLPC.

An exciting aspect of this BookSprint is the international effort behind it. Adam Hyde, founder of Floss Manuals, is planning to make the trek to Austin from Amsterdam, and there’s a French Floss Manuals coordinator working behind the scenes to ensure that the document can be translated to French. I’m also working with Yama Ploskonka, admin of the OLPC-Sur list of Spanish-speaking OLPC supporters to find Spanish language translators.

All in all, this is a very exciting effort and I’d love to get readers of JustWriteClick involved in any way you’d like. I’m very excited to be part of this effort and pleased to play host – let’s gather some more community around the BookSprint to make it a success.

tools writing

New look, same content

Just updated my blog with a new green theme, Corpgreen from Blog Oh Blog. I think I’ve tweaked appropriately, such as changing the RSS feed URL in the welcome.php file, but do let me know if you see anything amiss.

I also got the Identicons plugin working again, which are those neat icons for a comment that look like quilt blocks to me. They’re designed using an algorithm based on the IP address of the visitor, but can’t directly identify the person.

I’m thrilled with WordPress themes because of the really simple, straightforward way of separating format from content. I learned alot about CSS and the theme by using the Web Developer plugin for Firefox to visualize the div boxes.

Let’s just say, themes are complex, but can be broken down into their parts pretty easily once you have the visual tools you need.

Uncategorized

Understanding the database implementation of Author-it

Author-it uses a SQL Server database to house all of the source material that make up your deliverables. You can export that database content to XML and publish to Word or HTML and other outputs, but the source is stored in a database.

For locally-run databases (meaning that Author-it and the database are on the same computer), you can use a Jet database (also known as Jet, or MSDE, or SQL Express) to store your content. Updated to add: With a Jet database, your content cannot 2 GB and the upper limit for users is 5.

For server database installations, where the content is stored on a separate database server, you can use SQL Server 7.0, SQL Server 2000, or SQL Server 2005. You can use a pre-existing SQL Server database such as one that your company uses already by simply asking for a database to be created with certain permissions already set. That configuration is what we do at ASI.

You can also install and run your own SQL Server database using SQL Express which is relatively painless to set up and the installation instructions from both Author-it and Microsoft are detailed and thorough. The limitation for this configuration is that your Author-it library cannot exceed 4 GBMB.

Here are some helpful links for researching the database aspect of Author-it:

Installing Author-it

System Requirements for Author-it

techpubs tools Uncategorized writing

STC Intercom – Editorial Calendar progress

Thanks everyone for the great comments and feedback on our starting list of theme and article ideas for STC Intercom‘s 2009 editorial calendar. I appreciate that comments are still coming in, from all around the globe. I’m enjoying the international and generational communication we’re seeing, so thanks very much!

We posted ideas and requested feedback on blogs, the STC forum, and tapped Ed Rutowski’s experience and knowledge as well as hearing results from survey data he has gathered over the years. All venues have resulted in view points and reflections that are helping us on our journey to assemble an editorial calendar for next year’s ten issues.

In the weeks since I posted that entry, the advisory panel has met twice. In between the two meetings, we performed what is called a card sort using the web application at websort.net. I thought I’d share our process with you, since I found it fascinating, but also because the card sort was extremely helpful so that we could narrow down and focus the ideas from 50+ to just 10.

Websort is a Web-based card sorting tool, and the site’s intent is to help web designers improve the organization of their site. Panelist Rhonda Bracey had used it previously and thought it would be a good match for our needs. Great thinking, Rhonda!

To create our study, I used a list of keywords created from our brainstorming and invitations to the larger community to give their feedback. I had stored the keywords in a Google Spreadsheet, with one column for the keywords, and a second column for a more detailed description of what the originator meant by that idea or concept. I was able to copy and paste the keywords into the sorting tool, and then create tooltips for participants to see the longer description when they hoovered their mouse over the keyword.

Next, I sent the invitation to participate to the editorial advisory panel using the WebSort tool and the list of email addresses. Whenever a participant completed the study, I could use an RSS feed to be notified. It took me about 45 minutes to complete the study myself.

Once everyone had done the sort, I could view the results and analyze them in different ways. One analysis is called a tree view, which I sent to everyone in a PDF file that you can download. The groupings are bunched as if in a tournament bracket, with groups colored red or blue, and it offers a visual representation of how the participants grouped things in common, although the names of their groupings do not appear. You download the tree words list separately.

You can download a spreadsheet analysis tool after the study is complete, and then download and an Excel macro that takes the tree words list and compares it with each participant’s list and groupings. It produces a set of frequency tables for each item, containing a list of the groups in which that item was placed across all the participants.

Before our second meeting, I sent out the tree view PDF file and the spreadsheet with the macro run on the data. During our meeting, we then discussed the results and analysis and seven topics were clearly indicated. Our job then was to ensure that we had three theme-worthy categories and also to make sure that no topic slipped through the cracks or was ignored completely.

We discussed the difficulty in choosing a theme that will have the right content so that any issue of STC Intercom has something relevant to nearly all members, despite knowing that technical communication contains a diverse set of jobs, tool sets, and career paths.  Our hope is to produce a set of themes that are relevant and that we’re realistic about recruiting writers for the articles.

We’re still working on the final list and I’ll be sure to share it. STC Intercom’s editor, Ed Rutkowski, is leaving at the end of the month, and we’ll have our list ready for the new editor. Ed has served the Society for eight years and we’ll miss him. He has been great to work with – so best wishes to Ed at his new magazine editor position! If you know a qualified applicant, and STC members are encouraged to apply, review the job description and follow the instructions in the announcement linked from the STC home page.

techpubs tools work

Publish a Word outline using Author-it

At ASI, we’re working on book skeletons while we do task analysis for new documentation or feature updates that may change the way users do their work with iMIS. So, to get early feedback, we wanted a way to publish an outline of that skeleton book with no page numbers, but headings and subheading levels indicated clearly.

My first attempt at a macro called within the AfterPublish macro gave me the inverse of what I wanted (content but no outline), but my coworker Mary Connor, being the VBA expert that she is, came up with a working macro. It basically says, if you’re a section break after the 2nd section break, throw that content away but keep the table of contents content.

Here is an overview of the steps to get an outline out of a book made in Author-it.

These are pre-requisites to the publishing step:

In Author-it, create a six-level TOC object that doesn’t contain page numbers. Six was the number of levels we thought was an extreme case, and you can’t go higher than six levels of heading in HTML anyway, so six seems like a good number for us. Your situation may vary.

In the .dot file that contains your AfterPublish macros, create a TrimToOutline macro that contains this code:

Sub TrimToOutline()
'
' Freezes table of contents field, then strips off everything after the contents:
' Macro recorded 6/26/2008 by Mary Connor
Dim dSection As Section
Selection.WholeStory
Selection.Fields.Unlink
For Each dSection In ActiveDocument.Sections
If dSection.Index > 2 Then
dSection.Range.Delete
End If
Next
End Sub

In the Sub AfterPublish() area of your Word template file, put a call to TrimToOutline.

In Author-it, create a new book template for outlines, and point it to the .dot file that contains that macro code above.

Next are the steps for publishing your sub-book content to a Word outline-only document. It’s not actually in the Word outline view, but rather, a table of contents without page numbers, but based on the skeleton sub-books placed within the book you’ll create below.

  1. In Author-it, create a book using the outline book template that you created previously.
  2. Drag any sub-books into this new book and save the new book.
  3. Publish to Word.
    The resulting Word document should contain only a title page and a table of contents.

I’d love to hear feedback or ideas for improving this specialized output for Author-it, so please feel free to comment.

work

The art – and instinct – of productivity

I just completed David Allen’s excellent book, Getting Things Done:The Art of Stress-Free Productivity. I found that some of his tips I do instinctively, yet perhaps not yet naturally, but this book helped me apply practical principles to time management. Plus, he shows us that it’s not always easy to get to “what is the next action?” in collaborative environments. Much discussion may go into that very question.

I love to be very busy, and the Getting Things Done book helps me realize that I’m as busy as many others, and perhaps less busy than some. He even says that you can have as many as 50 Next Action items on your list when you combine work and home actions and projects. What a relief it was to read that! I’m not overly busy or scheduled, I’m merely able to write down what it is that needs to happen next. I also found it a relief to keep all home and work action items in one place.

My favorite description of the natural instinctive planning process that some people can hold in their brains comes from This Woman’s Work, Dawn Friedman’s blog. She’s a writer and mom in Columbus, Ohio. The post is titled “Life inside my head” and my favorite sentence has to be this:

Then there’s baby wardrobe — if I use the really good all-in-one dipe to take her to grandma’s then I won’t have it for the playdate tomorrow, which is ok except the other ones are a wee bit leaky so I should use the regular poofy diapers and then I’ll need to put her in the other outfit with a big enough tush but that one is maybe a tad too warm so I better check the weather forecast before I make a move at all.

Sheer parenting inventory time management awesomeness. What are some of your favorite examples of extreme time and resource management?

techpubs Uncategorized writing

We’re not Amish, we just don’t have a TV

I grew up in Goshen, Indiana, a college town of about 20,000 people with many Amish and conservative Mennonites in the surrounding communities. Seeing horse-drawn buggies parked at the local Wal-marts (yes, there was one on each side of town) was not uncommon. I learned to love the simple quilt designs and homemade Dutch food, while appreciating the business and common sense displayed by those selling their wares.

Last month at the STC Summit, I had a great walk back through time, as if I was visiting an old neighborhood. Like many other attendees, I went across the street from the Philadelphia conference center to the market for lunch. Much to my surprise, many merchants were wearing conservative Mennonite prayer bonnets and dressed in handmade plain clothing, no buttons! I was immediately taken back to my childhood home in northern Indiana. The marketplace in Philly reminded me of visits with my parent and shopping in a large market in a town called Shipshewana. Has anyone else had such a moment of juxtaposition?

To further my reminiscing of my childhood closeness to the Plain orders, the first day of the conference, I read Howard Rheingold’s Wired magazine article, Look Who’s Talking, from 1999. The subtitle is “The Amish are famous for shunning technology. But their secret love affair with the cell phone is causing an uproar.” It’s about the Amish relationship with technology and community. A great read!

I was reminded of a discussion with one of my cousins. We didn’t have a TV for a few years when I was in fifth grade or so, and these cousins from Michigan inquired if we were Amish! My response? No, we’re not Amish, just taking some time off from TV ownership. :)

So imagine if you will my discovery of Clay Shirky’s blog entry, Gin, Television, and Social Surplus. In it he leads you to discover that Wikipedia’s creation and ongoing editing took about 100 million hours of human thought. Sounds like a lot of time, right? Many people ask, how does anyone have that much spare time to edit wikis, write blog entries, comment on social networking sites, and so on? Well, guess what. In the US alone, 200 billion hours of human time are spent watching television. Staggering thought.

My few childhood years without a television didn’t amount to any huge projects being completed, although I would guess I read faster and more hungrily because of it. Don’t get me wrong, I’m not against TV. I just choose to watch what I want when I want to. Our Tivo has been the best enabler of TV when I want it, and having the shows I want always available when it’s convienent to watch them. RSS feeds are like Tivo for me – web content when I want it, in abundance.

So that’s my story of going from surrounded by Amish and their considerations for technology in their community to technical writer considering the impact of collaboration and conversation and community on my role in the world of participatory media.

Am I to be a content curator or a community manager? Rachel Happe has a great blog entry titled, “Social Media is not Community” which brought a lot of clarity to my thoughts about the difference between the two roles. Thank you, Rachel! I don’t know yet where my role lies, but it’s a grand time to be reading and writing about it. I’d love to hear your thoughts.

DITA

Notes from April 2008 Central Texas DITA User Group meeting

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.

Real life, online life, all mashed up

Nike plus running loop Mashups and virtual worlds are more and more a part of Web 2.0, and perhaps as an extension, part of social media. An example of a mashup that is social is on Nikeplus.com, where I can map out running routes using Google maps. The “mashing” is defined by me, a user, using Google maps to customize the running routes around my neighborhood, and sharing them with others in the Nikeplus community.

Another example is Twitter meetups – where someone on Twitter just says a place and time and anyone can show up.

Virtual worlds, such as Second Life, are already part of technical communication for training delivery or for virtual meetings. Training organizations are already finding the value in offering training programs on Second Life, where people can gather with avatars that represent their personalities online.

Here’s a term that was new to me – machinima, a mashup of machine and cinema. Machinima is a recording of Second Life’s environment. In Second Life, you can build any visual you need. Avatars can be used to do corporate training – apparently John Hartman experimented with this idea a few years ago.

For a final real-world-online-world mashup, take a look at chorewars.com. It’s a great example of how real life social and computing are merging. Around Austin, startup companies sometimes save money by crowdsourcing the janitorial work for a small office. Corewars is a perfect solution for that scenario. If you are parenting teenagers or cleaning up at a startup, it just might work well in your life.