Category Archives: DITA

DITA tools wiki writing

Notes from WebWorks RoundUp 2009

I attended two days of the WebWorks Roundup here in Austin this week and served on a few panels. I enjoyed signing books as every attendee got copies of books from XML Press. It had featured speakers like Tom Johnson and Stewart Mader as well as sessions with Lisa Dyer and Alan Porter to name a few. Here are my summary take aways from the sessions.

Wiki adoption

Stewart Mader is a wiki consultant, probably the most experienced, practical, and sensible wiki adoption expert available today. His message about wiki adoption resonated with me as I look for collaborative authoring solutions for our Agile teams. He said, if you look around the enterprise, people have high adoption of email for their daily business tasks. In the adoption phase for a wiki or collaboration system, you can tie a wiki to email conceptually as this ubiquitous useful way to get work done. If you think about it, more complex systems have a higher learning curve, so people default back to email to get into their comfort zone. But, sending email messages is an isolating experience – email doesn’t let you work together collectively like a wiki does.

For example, working in the shared space of a wiki is like using light rail to get to work. He has made friends on the train he took each day years ago and he’s still friends with them today. In other words, being in an environment that enables social interaction is more powerful. He says to think about the business process a wiki affects – do not just apply what the Internet says to do with a wiki. The biggest and most powerful collaboration going on with wikis in the enterprise is group collaboration – small groups. You don’t want one-off contributions once, you want repeated collaboration and repeated use, as frequent as email and as a simple core tool that they use for everyday business. Preach it, brother!

He also talked about measurements to indicate that adoption is successful. One of the biggest dangers he sees is counting the number of pages created when adopting a wiki. Don’t do it! Better metrics are measure per time period or per some other unit:

Views                    Day
Revisions      per       Page
Comments                 Unit
Tags                     Type

Automation – 1001 Nightly Builds

Some of WebWorks’ customers gave talks and a panel discussion about automating software builds using WebWorks Automap. These were great eye-openers and my ears perked up because they were writers working in Agile environments. They have to release in tandem with internal development cycles, so they automated as much as they could. One doc group used to have a 15 page document on how to create a PDF complete with screenshots for all the settings. Mary Anthony from Palantir said their writers have to document 4 user interfaces, 3 admin GUIs, more than 12 servers and an API, and they used advanced techniques such as text insets in FrameMaker. Using WebWorks, another writing group had automated PDF generation, wiki output, plus HTML output, all from Framemaker source files.

This was interesting to me – they found there was a true documentation domain and it was hard for someone who usually builds software for them to put together docs. Terms like cross references, text inserts, and so on, were foreign to their build engineers. They don’t even have the concept of “book” as a collection of chapters with a TOC in Framemaker. Even using a Windows server to automate builds was outside of the build engineer’s knowledge.

I learned about a tool called Apache Ivy, which is an agile dependency manager. Using this manager helped them integrate their documentation builds with the product builds. Mary Anthony explained that Ivy waits for the outcome of another build – like a refrigerator holding chocolate pudding, Ivy opens the fridge door and gives the build process what it wants (the chocolate pudding, or the fine documentation).

Overall a great couple of presentations about automation from which I learned a lot.

Blogging and Web 2.0

Tom Johnson is a blogger and technical writer and likely the most subscribed-to blogger in our particular tech comm niche. He gave a great talk based on his blog series, Seven Deadly Sins of Blogging. In case you’re curious, the sins are being Fake, Irrelevant, Boring, Unreadable, Irresponsible, Unfindable, Inattentive. (I’ll link to the rest once he has the blog posts finished.)

He had great pictures representing each sin. My favorite quotes were from Penelope Trunk (The Brazen Careerist, Blogs without topics are a waste of time) and Stephen Fry’s blog entry, “Don’t Quote Me“.

This session was a great starting point for our next panel about Web 2.0, although we mostly talked about blogging. The Technorati State of the Blogsphere 2009 report came out yesterday, so it was useful to talk about some of the findings from it (73% of bloggers use Twitter as compared to 14% of the general population, for one.) I enjoyed talking with Alan Porter and Tom on this panel and I may have asked as many questions as I answered. All in all, a great two days of discussion and presentations.

Progress on the Conversation and Community book

The final details for my book, Conversation and Community: The Social Web for Documentation, are coming together. Lots of news to report, so here goes.

I’m so excited to announce that Eliot Kimber has agreed to use my book for the DITA for Publishers project, taking the content from Adobe InDesign to DITA.

Tom Johnson also posted a fun interview he recorded during the STC Summit. I told Tom, I can hear myself grinning. This book is just fun to talk about.

I’m often asked, how long have you been working on it? I answer that I’ve been working on it for over a year now. It combines lots of stories from my corporate blogging days at BMC Software with my foray into the open source community with the One Laptop per Child project, SugarLabs (the education project that runs the open source software on the OLPC laptop), and most importantly, FLOSS Manuals, providing free software for free documentation. My thirty-hour work week at ASI has afforded me the time to write out my journey and my observations along the way.

What a journey it has been and I’m so pleased with how the book is turning out. This week I am furiously indexing (is there any other way to index besides furiously?) and often messing with recto and verso pages, something I haven’t done in InDesign before and boy does it show. My PageMaker days as a graduate assistant at Miami University’s Center for Chemical Education are coming in handy, no doubt about it.

I think we’ve finalized the cover design, which for me is a very exciting part of real bookmaking! I’ll see if I can share it on my blog soon.

Four fine people have agreed to do technical reviews and I know some of them are at least 100 pages in. I hope they have insights – but not too many that may cause me to think too hard. Just kidding, Alan, Will, Sarah, and Scott! 🙂 Keep reading and keep your notes at the ready because I’m ready to make all the changes needed to keep this project rolling. This book’s time has come.

Climb collaboration levels with me in Atlanta

stonestairssomerights20 Photo courtesy lollaping
I finished my presentation about Climbing the Levels of Collaboration for the Collaboration Institute at the STC Summit and I’m so excited about it I can’t stand it! True confession: I was up until 1:00 AM finishing it up and uploaded it quite late.

I found this great collaboration exercise that I’ve incorporated into the session. So we’ll be drawing with Crayola markers. Maybe even collaboratively. I’m hoping for quite the Back of the Napkin experience. 🙂

This session walks through the different ways you can collaborate with your users (and co-workers) especially when wikis are enabling the collaboration. I’ll be talking about Book Sprints and FLOSS Manuals and tell stories from my experiences. I was inspired by the examples of amazing group accomplishments described in Clay Shirky’s book, Here Comes Everybody: The Power of Organizing Without Organizations. While shopping around the ideas for the talk, I emailed people and asked what they thought of this description:

Groups can take action even quicker than ever before in history thanks to tools that amplify group communications such as wikis, blogs, and instant messaging. There are three distinct levels of collaboration that a group can attain and what they accomplish directly correlates to the level of collaboration.

People I talked with definitely wanted to know best practices for wiki authoring techniques. One person even wanted to know how to incorporate user-generated content into their help system. I’ve heard that request before – such as, how could you import wiki content into Robohelp? Also, what I learned at last weeks’ talk was a high number of people wanting recommendations for wiki engines. There are over 90 to choose from on Eep. Writers also wanted to how to organize content on a wiki. I won’t promise to have all the answers or any of the answers but I am looking forward to sharing my stories and hearing yours.

blogging DITA OLPC techpubs tools wiki

What is Anne Gentle up to?

I finally feel some energy returning after my eye injury about a month ago, although my right eye remains dilated which still means that side is a bit out-of-focus and I don’t like driving at night. I feel like I need to give a status update or some such. So here goes.

Winter Camp

boxartWith luck my eye should be just fine in time for a big event coming up: Winter Camp 09 the first week of March. I’ll be representing and working for FLOSS Manuals at this event, held in Amsterdam. From the description, it will be an amazing week:

Network Cultures Winter Camp will be a mix of presentations and work spaces with an emphasis on getting things done. It will be a four-day program of work spaces and plenary presentations, in which a dozen networks (each of which has 5-15 people) can work on their specific current topics.

The format was inspired by a cardboard box art installation that activates a temporary warehouse of contemporary knowledge from what I can gather from a translation of the page, Re-fitting ideas. Come on, that’s incredible. I am so thrilled to be a part of it. And I know it’s going to be a week of hard work.

Preschool website completed, using WordPress 2.7

We’ve also finished the preschool website I mentioned in my interview with Michael Silverman of Duo Consulting. We used WordPress hosted at Midas Networks. I recorded some screencasts with Jing to show other parent volunteers how to edit content and work with images. All the photos on the site were taken by parents so it’s quite the “do-it-yourself” website. I am hoping that WordPress 2.7 will be easy enough for even those in our volunteer and staff group who are not technically savvy but still give us the growth towards more content creators that we have in our goals for the site.

FLOSS Manuals and OLPC

We’ve sold over 200 copies of the OLPC Laptop Users Guide on, and Adam Hyde gave a copy of one of FLOSS Manuals’ books to Bob Young, the CEO of Lulu, while they were at the O’Reilly Tools of Change conference. Impressive. I still plan to make the Sugar Users Guide better. Adam Hyde and I are working on a book about how to run a Book Sprint in FLOSS Manuals, naturally, and we would welcome additional contributors.

DITA and Web 2.0

I’ve been approached to help put a public face on standards for DITA and Web 2.0 projects such as DITA for wikis (an example is Lisa Dyer’s DITA2Wiki project on SourceForge) and DITA for blogs (another example is DITA to WordPress or DITA and microformats).

STC Intercom Editorial Advisory Panel

I’ve been pretty impressed with the STC Intercom issues in 2009 so far, but I wrote one of the articles so perhaps my judgement would be playing favorites. I would like to gather feedback from STC members and non-members who read the articles – how’s the content grabbing you this year?

Author-it 5.2

It looks as though 5.2 is the version of Author-it that will allow us to upgrade from 4.5. Our content just wouldn’t publish adequately (Word or HTML) on 5.0 or 5.1, but now that 5.2 is released, fingers crossed, we’ll be moving to 5.2 soon. I should write a blog post about some of our testing on our 20,000+ object database. I’m getting used to the Ribbon Bar as I continue to work in Word 2007, and Author-it’s 5.x interface feels a lot like Word 2007.

Writing a book, do tell me what you want to know

Last but certainly not least, I’m working with a professional editor to try to finalize my book about documentation as conversation that examines the power of social media for writing projects. It walks through the myriad of possibilities of different types of social media tools and analyzes how writers and communities are using these tools for technical documentation. Look for it this spring!


InfoSlicer is released to the world

Let the remixing begin. I just got word today that the Infoslicer project has been checked into the Sugar code repository at, and released under the GPLv2 license. Can I get a whoohoo? Oh yeah!

Infoslicer is a Sugar Activity that enables students and instructors around the world to assemble Wikipedia articles into new information packages. Under the covers one of the technologies that makes this possible is the Darwin Information Typing Architecture (DITA). I first wrote about the InfoSlicer last fall, in Wikislicing project gets real – introducing InfoSlicer as a Sugar Activity with a picture of students using scissors to re-assemble Wikipedia articles.

If you want to download the Activity to your XO or another computer with Sugar installed (here’s how) to try it out yourself, go to and install the Activity (here’s how).

I have downloaded it to my XO in anticipation of showing it off at the next XO Austin Users Group meeting and the install was straightforward. I’ll get it on a USB stick to share at the meeting (2/16 at Central Market on N. Lamar in Austin at 6:30). Here’s a screenshot – and be sure to check out the YouTube video!


Laura Cowen notes that the xo package that you download doesn’t contain any sample articles from Wikipedia (which ideally it would to help you get up and running more quickly using the tutorial). You can use InfoSlicer without these sample articles (you download Wikipedia articles from within InfoSlicer anyway). If anyone is able to re-compile the xo package with sample articles in it, Laura can provide instructions on where to put the sample articles in the package so that InfoSlicer automatically picks them up when it starts. Who wants to create the wikislice seen ’round the world?

agile DITA techpubs wiki

Structured Wikis and Software Engineering – Documentation Throughout the Process

Lisa Dyer and I have co-authored another paper about structured wikis, using DITA as the structure for the wiki. The paper contains specific ideas about using wikis both internally and externally for software engineering processes and software documentation.

Our assertion is this: While either waterfall development methods or Agile development methods could benefit from the collaboration a wiki offers, we believe that DITA typing combined with the wiki collaboration offers even greater benefits than DITA alone or a wiki as a standalone authoring environment.

We think this one is worthy of a price tag, so it’s available for sale here at Just Write Click. You don’t need a PayPal account to purchase if you click-through the links that don’t require you to login to PayPal, you just need a credit card. Once you purchase it, you’ll go to a page with a download link to the PDF file. We’ve discontinued the selling of this paper and thanks to those of you who purchased it, read it, and took off with the ideas!

You can now download the paper originally submitted to the Wikis 4 Software Engineering at WikiSym 2008.

We’ve revised it based on feedback from three reviewers who had excellent commentary and were not technical writers, so it should contain useful information for technical writers, developers, software engineers, business analysts, project managers, and quality assurance engineers.


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

DITA wiki

DITA Meets Wiki – Output DITA to Wikitext

A few years ago I wrote a blog entry on 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 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 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.

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 for more information.

Watch a demo of the InfoSlicer Activity in action here:

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!

DITA techpubs work writing

Darwin Information Typing Architecture (DITA) reading list

Here’s a reading list for DITA materials when you’re just getting started. I’ve been fielding some questions via email and IM about DITA lately, and pulled this blog post out of my drafts. I hope it’s helpful.

Learning more about DITA

Getting started with DITA

Structured writing, structured documentation

BMC Case Study featured in The Rockley Report:

Is DITA Going to Tip? By JoAnn Hackos in the CIDM newsletter

Introduction to DITA book cover
Introduction to DITA: A User Guide to the Darwin Information Typing
book by Jennifer Linton and Kylene Bruski.

Planning for DITA Success: How to Set Up the Right Team and the Right
Strategy, Part I, by Steve Manning of The Rockley Group and Su-Laine
Yeo of Blast Radius

Planning for DITA Success: How to Deploy DITA, Step-By-Step, Part II,
by Steve Manning of The Rockley Group and Su-Laine Yeo and Paul
Prescod of XMetaL

10 DITA Lessons Learned From Tech Writers in the Trenches

Updated to add:
ISTC Communicator articles about DITA (2005-2007)