Subscribe to RSS
Posts Tagged ‘Lombardi’
Amazing conversations and meeting amazing people at SXSW Interactive
South by Southwest Interactive is a big web design/blogging conference in downtown Austin. There are thousands of people here for it in 2008. It’s crazy busy.
The latest excitement was in a friend’s panel where people tried to stage an uprising on both Twitter and in the meebo room at meebo.com/sxsw, set up specifically for this talk. Tom Parish has a great picture and is quoted in this Wired blog story. The very next day, the Zuckerburg interview had a similar uprising on a much grander scale. Jeff Jarvis has the best analyses I’ve read so far about it, and Scoble’s view from the Twitter gallery is also a good read.
I’m of two minds about the things that have happened here this week - on one hand, I think the conference is only as high quality as its presenters. If all the attendees think they’re smarter than and better than the panelists, then why bother coming at all when you can view the video online or listen to the podcast later? I guess that hypothetical question is answered with - we come because we can interact with the panelists.
I even witnessed a panelist admit that he “wasn’t paying attention” to another panelist’s answer to a question during their panel. It came across as immature, arrogant, and unprofessional to me. Much like the sweater-tossing antics I observed based on the meebo room conversation in the social media metrics talk, I internally rolled my eyes and thought, how many people are just trying to get attention, drawing it away from the panelists disrespectfully? Is this online behavior and real-life behavior only as mature as the junior high lunch room?
On the other hand, if all the panelists preach about user-centered content, then when the choir stages an uprising, the preacher should be able to adjust his message to fit the audience. Right? I really admired Tom’s quick thinking. I was admiring the way that Tom handled the panel, ensuring that the podcast recording turns out well also, by having each speaker introduce themselves so that listeners later can identify voices while listening.
But enough about the conflicts and struggles going on between panelists, interviewers, and SXSWi attendees. This year, my interaction with other attendees has been the most exciting and fun for me.
Before and after the social media metrics talk, I befriended two guys from Washington, DC, and Summer from Austin who were all sitting around me.
I ended up giving a ride up Sixth Street to David, one of the guys from DC, and he and I had the nicest conversation on the way to BarCamp. I had asked about the conversations that occur on wikis and how interesting it was that the WoWiki panelist George Pribel said they never want to answer how to or troubleshooting questions on their wiki, that they only wanted articles and discussion around strategy. I said that as a tech writer, I was looking for the best use of wikis for content, but since we usually live nearest to and offer the most value to the customer support department, our wikis would be shaped more towards howto and troubleshooting information. However, best practices and strategy wikis might be more easily shaped for conversational articles, so, which was the better approach? His answer was spot on and an excellent example that will stick with me. He said, it’s just like the real world conversations you have in a crowd. If you and I are talking about movies, and someone comes up and starts talking about their favorite restaurant, we would politely inform them that we’re talking about movies, and could you take your food conversation elsewhere, maybe to the person sitting next to me? It’s a matter of staying on topic. With wiki design, I would conclude, you might want to prepare for two audiences (and two types of conversations), just like Lisa Dyer has done at Lombardi Software.
After attending David’s talk, WhiteHouse 2.0 at Barcamp, I learned that he’s former White House Internet and Communications Director David Almacy! He started RSS feeds and podcasts on iTunes and Tivo for the president’s white house. He wrote a Barney Cam script that got posted on Youtube and had over 25,000 views that season. As it turns out, he has two daughters nearly exactly the same age as my two sons. Our youngest kids were born within three days of each other. He was so nice and professional, a knowledgeable expert who is also willing to share his experiences. Prior to the social media metrics talk, I babbled about how I was a blogger for Ynema and Tom on talk.bmc. Little did I know of my fellow attendees level of experience with social media, but I was so pleased that David didn’t try to prove just how much more knowledgeable (and famous) he is than I. Instead he just answered my questions and truly listened to me.
I’m still amazed at the serendipitous meetings and conversations. Yes, the attendees make the conference interesting, and the panelists are bravely facing those attendees.
DITA and wiki hybrids - they’re here
Lisa Dyer and Alan Porter presented at last week’s DITA Central Texas User Group meeting, and both told tales of end-user doc written and sourced in DITA, with wikitext in mind as an output. About 20 people attended and we all enjoyed the show. I wanted to post my notes to follow up, and I’ll post a link to slide shows as well.
This post covers Lisa Dyer’s presentation on a wiki sourced with DITA topics. I’ll write another post to cover Alan’s presentation.
Although, actually, first, Bob Beims shared Meet Charlie, a description of Enterprise 2.0. Seems very appropriate for the discussions we’ve had at recent Central Texas DITA User Group meetings talking about wikis and RSS subscriptions and web-based documentation.
Lisa has made her presentation available online. My notes are below the slideshow.
[slideshare id=301959&doc=lombardi-wikis-model-1205252771520550-4&w=425]
DITA source to wiki output case study
Lisa Dyer walked us through her DITA to wiki project. Their high level vision and business goals merged with a wiki as one solution, and Lombardi has customers who had requested a wiki. Lombardi’s wiki is available to customers that have a support login, so I won’t link to it, but she was able to demo the system they’ve had in place since July 2007.
What wiki toolset - open source or entprise wiki engine?
On the question of choosing an open source or enterprise wiki engine, Lisa said to ask questions while evaluating, such as where do you want the intellectual property to develop? Will you pay for support? Who are your key resources internally, and do you need to supplement resources with external help? They found it faster to get up and running and supported with an enterprise engine and chose Confluence, but she also noted that you “vote” for updates and enhancements with dollars rather than, say, community influence. (Editorial note - I’m opining on whether you get updates to open source wiki engines through community influence. I’m certain you can pay for support and enhancements to open source efforts with dollars.)
Run a pilot wiki project
She recommends a pilot wiki, internal only at first, to ferret problems out while building in time to fix the problems. While Michele Guthrie from Cisco couldn’t present on the panel at the last minute, she also has found that internal-only wikis helped them understand the best practices for wiki documentation.
Meet customer needs - or decipher what they want and need
Lisa said that customers wanted immediate updates, knowledge of what’s new with the product and doc (800 pages worth), and wanted to tell others what they had learned. She found that all of these customer requests could be met with a wiki engine - RSS feeds, immediate updates, and the ability to share lessons learned. At her workplace, customers work extensively with the services people and document the implementation specifically, and that information could be scrubbed of customer-specific info. They found that rating and voting features give good content more exposure. Also, by putting the information into wikis, they found that there were fewer “I can’t find this information” complaints.
Intelligent wiki definition and separate audiences for each wiki
They have two wikis - one is for end-user documentation, one is for Services information. In the screens she showed us, Wiki was the tab label for the Services wiki, Documentation was the tab label for the doc wiki. The Documentation wiki does not allow anyone but the technical writers to edit content, but people can comment on the content and attach their own documents or images. The Services wiki allows for edits, comments, and attachments. The customers and services people wanted a way to share their unsanctioned knowledge such as samples, tips, and tricks, and the wiki lets them do that. The Services wiki has all the necessary disclaimers of a community-based wiki, such as “use this info at your own risk” type of disclaimers. Edited to add: The search feature lets users search both wikis, though.
Getting DITA to talk wiki
There are definite rules they’ve had to follow to get DITA to “talk wiki” and to ensure that Confluence knows what the intent is for the DITA content. For one, when they want to use different commands for UNIX and Windows steps in an installation or configuration task, they would use ditaval metadata around in the command line text (using the “platform” property) and use conditional processing for that topic. However, because of the Confluence engine’s limitation of one unique name for each wiki article, they had to create separate Spaces for each condition of the deliverable (UNIX Admin guide or Windows Admin guide, for example). This limit results in something like 12 Spaces, but considering it’s output for several books for separate platforms, 32 individual books in all, that number of Spaces didn’t seem daunting to me. She uses a set of properties files during the build process to tell Confluence what file set to use, and what ditavals they’re seeking, and then passes the properties to the ant build task. The additional wiki Spaces does mean that your URLs aren’t as simple as they could be - but in my estimation, they’re not completely awful either.
While I was researching this blog post further, Lisa also added these details about the Spaces and their individual SKU’s (Stock Keeping Unit, or individual deliverable). “Building on this baseline set of spaces, each new SKU would add 1 to 7 spaces hosting 3 to 21 deliverables, depending on the complexity of the ditaval rules and the product. Obviously, the long pole in this system is ditaval. A more ideal implementation would probably be to render the correct content based on user preferences (or some other mechanism to pass the user’s context to the engine for runtime rendition). Or, a ditaslice approach where you describe what you need, and the ditaslice is presented with the right content. Certainly innovation to be done there.”
Creating a wiki table of contents from a DITA map
She creates a static view of the TOC from the DITA map as the “home page” of the wiki. She currently uses the Sort ID assignment a DITA map XSLT transform to generate the TOC. She said they implemented a dynamic TOC based on the logical order of the ditamap by dynamically adding a piece of metadata to each topic – a sort id using a {set-sort-id} Confluence macro. The IDs are used to populate a page tree macro (the engine involved is Direct Web Remoting, or DWR… an Ajax technology). Currently, their dynamic TOC is broken due to a DWR engine conflict, which should be fixed in the next release. In the meantime, they are auto-generating a more static but fully hyperlinked TOC page on the home page of each Space. A functional solution, not great for back and forth navigation, but it shows the logical order which is pretty critical for a decent starting point.
DITA conref element becoming a transcluded wiki article
Another innovation she wanted to demonstrate was the use of DITA conrefs output as translusions in the Confluence wiki engine, so that in the wiki, the transcluded content can’t be edited inside of an article that transcludes the content. I don’t think it quite behaved the way she wanted it to, but knowing it’s a possibility is exciting. Edited to add: This innovation really does work, Lisa simply was looking at the wrong content (she admits, red-faced.) 
Burst the enthusiasm bubble, there are limitations and considerations
One limitation that I observed is that when you transform the DITA source to Confluence wikitext, there are macros embedded, so when someone clicks the edit tab in the wiki, they must edit in wikitext, not the rich-text editor, to make sure the macros are preserved. In the case of the Documentation wiki, they can instruct their writers to always use the wikitext editor. But, for the Services wiki, one attendee asked if users prefer the wikitext editor, and Lisa believes they do. Someone running MoinMoin at their office said they finally just disabled the rich text editor because they didn’t want to risk losing the “cool” things that they could do with wiki text. The problem at the heart of this issue is that if users really like the wikitext editor and do a lot of “fancy” wiki text markup (like macros), then another wiki user using the rich-text editor can break the macros by saving over in rich text. Edited to add: Lisa wrote me with these additional details which are very helpful - “actually, the macros are preserved when in Rich Text Editor (RTE) mode. the problem is that it looks ugly as heck – and if the user is not techie, potentially confusing. the RTE does add all kinds of espace characters to the content– in a seeming random way - and can negatively impact the formatting in general when viewing, but it doesn’t seem to affect our macros. However, if a user wants to use macros to spiffy up the content, then wiki markup mode is definitely recommended.”
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.
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.
