Monthly Archives: October 2008

techpubs

Keeping up with Technology + Learning and DocTrain East

I’m eagerly awaiting blog entries and Tweets from DocTrain East – Adam Hyde, the founder of FLOSS Manuals, is presenting about user-generated content (although we’d call it community-generated content I suppose). Subtle difference I’ll have to blog about sometime. :)  I’ve been reading the DocTrain Tweme page at http://twemes.com/doctrain and it looks like everyone is ready and raring to go. Scott Abel has also imbedded the Tweme page on the front page at http://www.doctrain.com/east, cool! I believe a good next step would be to use the cool registration application that was at Austin BarCamp last year – where you “signed in” with your Twitter ID and your arrival was announced to the @BarCampAustin, another cool integration of Twitter and real-world events. Good luck to all the presenters!

I also was reminded how closely education and training and technology go hand in hand – which happens to me often since I’ve been working on the One Laptop per Child documentation. I got a pointer to the T + L Conference (Technology + Learning) which overlaps dates a little bit with DocTrain East – but I also realized that many of the lessons learned from educators could be applied for our profession as well. I’ve been reading through the blog entries at the iQity blog including the virtual science lab post about using virtual simulations to teach science. I still haven’t found many examples of Second Life being used to train people on enterprise software but I suppose it’s a matter of time. The tween and teen kids using the virtual science labs will build training for us in the near future.

DITA

Notes from CenTX DITA Users Group – panel on the DITA Maturity Model

For our October meeting, we simply asked several Austin-based techpubs teams to review the DITA Maturity Model and to think ahead of time about how you would position your own DITA efforts:

Where do you think your team is in the adoption ladder?
Where do you want to be?

The DITA Maturity Model: A Stepwise Approach to Enterprise Content

  • Level 1: Topics
  • Level 2: Scalable Reuse
  • Level 3: Specialization and Customization
  • Level 4: Automation and Integration
  • Level 5: Semantics-on Demand
  • Level 6: Universal Semantic Ecosystem

The links to the paper are available either as PDF or HTML:

Here are my notes from the session – feel free to ask questions in the comments! Such a useful session – afterwards I thought “This session is exactly what user groups are made for.”

Lisa Dyer – Lombardi
2005 adoption
1.0 DITA spec
Level 4-5 currently

Wiki system and wiki output
Goal – dynamic personalization
Personalized content view on the wiki – what version, what release name
the users can use custom RSS feeds to “listen” to changes on that content.
Sets a sortID for each wiki page based on ordering of the DITA map which allows for TOC ordering on the wiki page.
Q: Audience for the wiki? A: Behind the firewall development wiki, also support login ID only wiki, external wiki has “warrantied” content plus another space for “community-generated” content.
When migrating, they put everything into Concept DTD, then put it into Perforce (didn’t get “where used” until went to CMS).
But CMS might slow you down. Analysis into paralasys – metadata schemes, “if we spend all this money we need to do it right the first time” pressure.

Mike Austin – Freescale
3 reps – 3 different business groups
started DITA process late 2004
Spread out across first 3 levels

Want structural mechanisms to make it easy to do right, but difficult to do wrong (don’t want artifacts left behind that clutter up views).
There are good political reasons for starting with a CMS if other teams are using it and want tools for finding the content they want.
Q: Does size of team make a difference or location?
A: Mixed… may depend on culture too. But definitely needed help on DITA maps, but Subversion doesn’t lock files it just tries to reconcile differences. Also, how well do you know target deliverables?

Colleen Reilly – Borland
Writer, has been there a year
March 2008, started implementing DITA
All of level 2 – but she doesn’t do level 3, but does do parts of level 4

Three products
Converted a user’s guide – - OEM to BMC Software – started out as FrameMaker files that went to RoboHelp, and another set of Framemaker

files and RH files for BMC templates. Plus translated to German and Japanese. BMC OEMed product is not quite the same as the Borland delivery – so variables helped immensely. Plus conditional text for a certain functionality that was only available in the Borland version. From four sources, back down to single source.
Structure of the document was more challenging.
Reuse – one file with all conrefs, all product names in that file
one file for the whole deliverable – common notes, common commands, plus even four steps at a time, commented heavily to let other writers know where to find content, plus other writers can find it if needed.

Several DITA maps – book DITA map, plus maps for each chapter.

Getting Started guide is 60 topics
API reference guide is 2117 topics
She is able to re-use content.
Q: How do you make sure all your topics are in the DITA map? A: She uses file datestamps to verify – and always adds new topics to the DITA map right away. Noreen looks for a red X in the CMS, but found that even if it’s used in the reltable it is seen as “used” in the CMS.

Sally Derrick -  Borland
Director of info dev services (tools group)

2.5, smatterings in level 4
Started in April 2007 – with a homegrown XML system
Converted
First specialization – glossary
Also since translate to Japanese, enabled See and See Also
Enabled cross-project linking for Eclipse help
2600 topics, 2100 in one document
Installation guides that are DITA – output to PDF only
Corporate glossary created in DITA
CMS is Subversion, still young at all this since they don’t yet have a lot of cross-product content re-use, but as products become more integrated, will have more re-use.
Q: Did you have “where used” in Subversion? A: Biggest status marker they use is “ready to translate” – Subversion attribute. Manually set everything to “no” then set it back to “yes” after its ready to translate.
Implemented context ids for context-sensitive help.

Sally has a t-shirt that says “I don’t nag, I’m a motivational speaker.”

Each team has a lead writer, 3 leads help make decisions.

Sally also manages translation managers – 3 vendors from around the world. XML translations are much better for translation memory, etc. Trados from SDL is one manager’s fav tool, other managers use different tools. Any good translation vendor is going to use translation memory – can reuse content that’s already translated. Author assistant tools may find reuseable paragraphs.

Noreen McMahan- Freescale
Works for Bob Beims – core infrastructure system person at Freescale and trainer for DITA
Agile approach – to scheduling projects
Their original goal was Level 1 by July 1 and they made it.
Leads came up with goals and requirements for achieving Level 1
Proceeded in 2-week sprints
Specializing conditional processing, feature based, structural domain specializations.
XML editor customization, Serna plugin lets it talk to Dakota CMS
One map type to get different output
Check errata content specializations
Plus semiconductor information for register specification for XML formats during design phase.
Also aligning metadata strategy with design source systems and repositories.
Wondering how the CMS could integrate with the web?
Also specializations for semantic tagging motivation.

Domain specializations, metadata strategy
Versioning, CMS another speciality
Integrating Open Toolkit with a widget that now works smoothly
She’s the internal trainer – uses the system and XML editor – giving feature requests.
Level 3 by Christmas

Tom Gihack- Freescale
Last business group to come to the DITA party
Consuming level 3 products from other groups – about to make bigger progress.
Half DITA, half FrameMaker implementation

Q: When you have a preponderance of information legacy vs. when you have DITA – which level can you achieve? Seems like you can get all the levels without DITA?
A: Levels of the model that make it easier to acheive with DITA – typical use case for Freescale – reference manuals that contain 12-15 chpaters specific to that product only, but 20-80 chapters that comes from all over different design centers. Struggling with the issue of combined legacy output – how can you recombine with a new toolset that uses both? Pipeline that starts with FrameMaker and then combines

p. 15 of white paper talks to the point that all of this is possible without DITA – what DITA offers is … refer to paper

Sally says “Content is driving us through the maturity levels.”
Get as much converted as possible, but only specialize when you run into a need for it.

Role-based presentation of the UI – then wouldn’t role-based help be great to go with the U

Can’t see them going further along maturity model ladder until all the content is converted.

For Lisa two the drivers – findability, implementing enterprise level content strategy (bringing other groups on board). Training group is bailing on instructor-led training, but may be led back to that since on-demand and web-based isn’t getting them the results they want. Really struggling. 80% of the coursework was in the user-doc already.
Siemens PLM at Best Practices conference.

150 information development groups at IBM – delivering right content, right person, right time via the right the channel

Lisa’s – Three years in, have more time to write.
Symantec – 5 years in to topic authoring, more time to write and bring customer feedback into the doc, analyze search requests

OLPC Uncategorized

BookSprint post on OLPC News web site

Here’s a post I wrote about the BookSprint published on OLPC News, an independent site that boasts about 5,000 readers a day.

To build a set of books in five days takes a lot of preparation work that Adam Hyde, founder of FLOSS Manuals, described in a prior post. Christoph also encouraged me to talk about what it was like to participate as a writer in the Book Sprint. Over all, it was very similar to a footrace of the same name, hosting a group of writers in a room cranking out as much usable content as possible! Read more…

DITA wiki

DITA Meets Wiki – Output DITA to Wikitext

A few years ago I wrote a blog entry on talk.bmc.com about combining DITA’s structured authoring principles with wiki’s collaborative, quick authoring style. The subtitle is “Darwin Information Typing Architecture, Meet Wiki” and I think that’s still appropriate. For quite some time, it was in the top ten on Google when searching for “DITA wiki” and today it’s a respectable 3rd or 4th hit.

I’m pleased to report on my blog once again about the possibilities of DITA and wiki – by reporting that there’s an open source method for converting DITA source files to wikitext output and even populating the wiki itself when using Confluence wiki. Lisa Dyer of Lombardi Software has been using this technique for about four years now in production, and she has generously given back to the community by starting the DITA2Wiki open source project on SourceForge.

Lisa has two blog entries describing both the initial release and this week’s update release:

Currently, it builds to Confluence Wiki, but its framework lets you extend it further to more wiki engines. I want to get a MediaWiki conversion going next, and I have joined the project in order to contribute. It would be great to have others join in the project.

I downloaded the DITA2wiki files, downloaded and installed a 30-day trial of Confluence wiki, and had working output with only a few troubleshooting incidents (I kept forgetting to change the path slashes from / to \ on Windows for the ant build properties file!) All the instructions for getting it up and running are on the SourceForge.net wiki pages for the project. I’ll sheepishly admit these are the pre-requisites I needed before I got it to work, in addition to the Troubleshooting that Lisa already provides:

  • Ensure you have a Confluence wiki running on the computer you’re using DITA2Wiki to build the output.
  • Ensure the URL and password for the wiki is correct.
  • Ensure the paths in the guide.properties file are correct. The two paths I had to change were the location of the DITA source files and the location of the DITA DTDs from the DITA Open ToolKit.
  • Each time you modify a path in the .properties file for a Windows environment, remember that the slashes are opposite direction from a copy and paste of the directory structure give you on Windows.

If you’re interested in using structured wikis and DITA especially in a software engineering project, you may want to read it on the Wikis 4 Software Engineering site. In it we describe how development processes, especially those using Agile development practices, can be streamlined and efficient when a highly collaborative and motivated staff has the right combination of wiki collaboration tools and training with structure added to the design and test documents shared on an internal wiki. The case study at the end shows how wiks and DITA end-user documentation work to give end-users the top layer of documentation started way back in the design process.

Uncategorized

Web Content Blogging at Duo Consulting

I’ve been writing blog entries related to web content, content management, and pretty much anything that catches my eye as related and relevant to web-based goods over at blog.duoconsulting.com. I thought I’d pull a collection together for my blog readers to browse as you wish.

“What are you working on?”

“On what are you working?” might be the more grammatically correct phrasing of this question, or perhaps the slightly awkward, “What work are you doing?” But the point is, you can let your coworkers and colleagues know your status updates internally only using Yammer, much like Twitter but with a co-worker limitation on conversations. Read more…

Why Luxury Brands Enter the Social Media Scene

The South By Southwest Interactive panel picker has done its duty and about 60 panels were announced last week, but one still caught my eye that did not get selected: Social Media for Luxury Brands and Brands With Issues. It looks like a very interesting discussion. Read more…

Twine for Networking Based on your Interests

I readily admit that the phrase “interest networking” sounds like Dilbert-speak to me. But I’ve been playing with Twine for a while (www.twine.com) and it seems appropriate to describe the experience as finding interests you have in common with other people. However, I don’t think its strength lies in networking because I still haven’t found how to import my contact lists to see who else I know on Twine. Read more…

Sunset on a CMS – Serena Collage

What do you do when your web content engine, while aging gracefully, indicates to you that it’s ready for the rocking chair on the porch? Read more…

Another, cooler aggregation example

As a side note, I love this idea of an online video conferece – Pixelated. It’s like this collection of blog entries but instead a collection of freely available presentation videos from TED Talks, YouTube, and Blip.tv.

Wikislicing project gets real – introducing InfoSlicer as a Sugar Activity

Scissor-style information slicing

Scissor-style information slicing

A photo of old school remixing – printing out Wikipedia articles and recombining them. :)

This was a fun learning exercise as part of an IBM Extreme Blue student project creating a Sugar Activity called InfoSlicer.

Instead of using scissors, you can now slice information by downloading Wikipedia articles, editing and remixing them, and reading them online. also uploading edits to Wikipedia (Edited: woops, that was part of our use case and it should work in the future because it was designed with that extension in mind).

Under the covers it is using the Darwin Information Typing Architecture, also known as DITA (dih-tuh), a standard set of DTDs (or schemas) that allow sharing of open source transformations and an open toolkit implementation. See dita-ot.sourceforge.net for more information.

Watch a demo of the InfoSlicer Activity in action here:
http://ca.youtube.com/watch?v=Y0UDRi37MWM

This Activity was part of the Wikislice Project. We met our goal of creating custom curriculum materials from Wikipedia for OLPC but we still have work we want to do to help teachers use it.

I can hear all the librarians and teachers of the world saying together – cool!

OLPC wiki

FLOSS Manuals book store now open!

I went out for a run this morning and realized it has been a year this very week since I started my volunteer work with OLPC. This project was my first foray into the open source world from a contributor standpoint, and I can’t believe how it has paid back at least tenfold in the people I’ve met, the lessons I’ve learned, and the technology I’m now acquainted with.

What did it take? For me, time and faith and trust in others.

This is an amazing day and it has been an amazing journey. And what is significant about today? We now have a FLOSS Manuals bookstore and we now have a real, hold-it-in-your-hands, put-it-on-your-bookshelf, book. With a cover designed by someone who works at MOMA no less. (Wow!) With content carefully authored by people who learned and knew enough about the technology while also considering who would read the chapters and what they want to do with the technology.

I’m happily and proudly displaying the distributable FLOSS Manuals bookstore on my blog – see the sidebar on the left? That’s a bit of HTML code that anyone can display and host a portable virtual book store on any web site. Here’s the code.

<style>
@import url("http://en.flossmanuals.net/bookstore/bookstore.css");
</style>
<img src="http://en.flossmanuals.net/bookstore/bookstore.gif"
style="margin-bottom:5px;">
<script type="text/javascript"
src="http://stores.lulu.com/feed.php?fStore=flossmanuals&fFormat=js"></script>

You can always download the PDF for free, but by buying a book you support the FLOSS Manuals project and help support the uptake and usefulness of free software by providing free documentation. Your money is well spent as these paperbacks are high quality and can take wear and tear. My hope is that people will read it and that the book will be passed on to the next learner.