This is a call to participate in an ongoing discussion around things related to single sourcing. Before starting a new forum area devoted to this subject, I’d like to gauge the interest of other members of this group by keeping all replies together under this topic. This is the area to discuss:
- Techniques for modular writing
- Practical application of the single sourcing methodology
- Enabling tools and technologies
- Innovative ideas on the subject
I missed the “Migrating single-sourced content in DITA XML to a wiki for field review”. Can you talk more about this topic?
Lisha’s comment in the Contractor’s Group post is what spurred this discussion. At DocTrain West, Lisa Dyer from Lombardi Group presented how her company built a system that exported DITA XML into a Confluence wiki to solicit feedback from SMEs in the field. Naturally, this system wasn’t completely open like wikipedia; users required appropriate login and publishing permissions. However, it is an interesting way to obtain real-time feedback.
April 2008’s Intercom published an article by Lisa Dyer, Anne Gentle, and Michael Priestley called, “Building a DITA-wiki hybrid.” As our forums audience are all STC members, you probably have this article in your bookshelf. Otherwise, you could download it. However, the best part is that because of the wide range of interest in this subject, the STC chose to follow the authors’ wishes, and made this article publicly available for download. Here: http://www.stc.org/intercom/PDFs/2008/200804_18-21.pdf
At DocTrain West at the beginning of May, I was privileged to meet both Lisa and Anne at an unconference where Lisa presented her business case, usage model, and demonstration of the DITA/wiki model. Lisa’s published her slides on slideshare.net, which you can link to through Anne’s blog. These slides were from a similar presentation given to a different group. Lisa used the same slides, but targeted it to the techcom in all of us, rather than the decision makers.
Lisa confessed that the DITA/wiki workflow only goes one way. From a technology standpoint, it’s easy to “dumb down” structured XML to html or wikitext. It’s harder to insert the semantic markup back into the html/wikitext to create structured XML. However, if the conversion engine devised a method to include semantic metadata within the body of the html/wikitext, then it could easily be restored, because it was never really stripped out.
Lombardi Group doesn’t think they would have trouble developing technology to roundtrip content from the wiki back to DITA XML. The hold up for them is in developing a business case for it. As wiki contributions are meant to be free form and multi-voice, their content requires significant overhaul before they can edit the DITA source. Automating the workflow for this process is pointless at this stage, because the content requires significant human involvement. However, they are open to partnering with anyone who wants to explore automating the wiki-DITA trip home.
Can anyone think of any other problems that automating this process would cause, rather than solve? Or does anyone have any ideas on what could make this process work? Note: I mentioned the possible use of metadata at the time the DITA source is published to the wiki. At this point I’m not sure Lombardi Group is doing that. I will have to ask them.
Lisa confessed that the DITA/wiki workflow only goes one way. From a technology standpoint, it’s easy to “dumb down” structured XML to html or wikitext. It’s harder to insert the semantic markup back into the html/wikitext to create structured XML. However, if the conversion engine devised a method to include semantic metadata within the body of the html/wikitext, then it could easily be restored, because it was never really stripped out.
I thought Wikis were supposed to be “the peoples’ editor.” What’s the reason for using a wiki with XML/Dita markup? And how would you maintain it on a larger wiki (if you don’t have dedicated editors, the wiki edits will get out of hand).
My humble experience with single-source documentation:
We get assigned some sw/doc update requirements from head office overseas for the product on which we do some development locally.
One doc goes to me. Fortunately the developer is in the building, as well as the spec writer/reviewer. Sometimes, they are not.
Through a virtual machine, I log onto the local node (in East US) of Ovidius’s Technical Communication Toolbox, the content management system we use.
I check out, update in FM+SGML, and check in various documents and embedded images.
I compile them in the product view and output a .pdf.
I ftp the .pdf from the TCT machine to my local machine for doc and technical review. I re-update and compile and ftp as often as necessary for changes that reviewers request. Some information will not be available for a while yet so i am assured of several visits to TCT for even a small document.
It’s a cumbersome process but a very secure system. I only need to update the bits of content affected, the doc template is centrally controlled and cannot be tweaked by “creative” writers. Many common doc sections are reused from existing manuals in the suite.
I thought Wikis were supposed to be “the peoples’ editor.” What’s the reason for using a wiki with XML/Dita markup? And how would you maintain it on a larger wiki (if you don’t have dedicated editors, the wiki edits will get out of hand).
Ah-ha! This is the beauty of wiki. You can have open, free-for-all access wikis, and closed wikis limited to certain user groups. For instance, our wiki is limited to members only. For a time it was limited to volunteers only. It is still “the peoples’ editor”, only now we have prequalified the quality of the authorship by the users with posting accounts.
So both clients and engineers end up collaborating on different sections of the documentation. And with wiki’s “no-delete, unlimited undo” feature, you never lose anything. Though I don’t know if Confluence wiki has a “talk” page either. Mediawiki excels at that.
The quality of edits, technical verification, and final say, are workflow problems that so far aren’t being addressed. I believe at this point Lombardi sets a deadline to manually freeze edits, take a wikislice, edit this data offline and manually apply the changes to the DITA XML source files. I think while they’d like to find a business case to automate this workflow, I believe the same as you that there’s no way a computer could completely replace a human’s involvement. Maybe, after taking the wikislice, the human editor takes over, but you’d still need someone on the other end of the DITA to review the output to correct conditional errors like extra punctuation, duplicate terms, etc.
Maybe the wiki-DITA workflow isn’t as easy a trip to take.
I ftp the .pdf from the TCT machine to my local machine for doc and technical review. I re-update and compile and ftp as often as necessary for changes that reviewers request. Some information will not be available for a while yet so i am assured of several visits to TCT for even a small document.
Hi Karl,
Are you the only writer on this team? I’m curious about how your company would work if you opened the floor to the SMEs to cut the first edits, and you edit the final draft and manage the review process.
One of the problems modular documentation solves is the ability to reuse content in blocks. SMEs wouldn’t have to write new content, only incorporate approved sections that have already been written, and add any conditional processing. This is what Bob Glushko called “content engineering”, which extends beyond mere technical documents.
When we treat everything from feature lists and specifications to task-based scripts and business transactions as content, we can mold more specific client profiles, and dream up new ways to engage them in the use of our products. This is a scary venture, even for me. I mean, Glushko’s example of how an ATM “remembered” his favourite withdrawl amounts and bill payments, and offered them by default upon login, seemed way too big brother for me. But it’s happening. Save-on Foods introduced an upgraded “more” card that links your purchases to their client database. They’ve always been able to track the amount of your purchases to calculate your points before. Now they will be able to create demographic profiles for different products, and customize their coupon offerings to only the product you buy, or similar to try. This data isn’t for your benefit. The product marketing depts, manufacturers, and distributors will all want their hands on that data. Ka-ching!
We don’t do single-sourcing globally where I work, either. Working on it…
Sorry, you’re right. I used a lot of buzzwords without any actual content. (I had just gotten out of DocTrain and was inspired to hack a DITA specialization because of a workshop I took on the last day. ;-) )
When we speak of roundtripping, we mean to take content created in one app, export it for editing in another app, and bring it back into the source app without errors. This is virtually impossible using current tools. It’s not enough to stop people from trying. The difficulty is on the return trip back into the source app. This app must be able to determine the differences between what it exported and what is being returned, gauge the impact of those changes, mark or act on them them appropriately, and return to work quickly.
I understand there are two schools of thought on technical writing. One is that information is gathered from Subject Matter Experts (SMEs) through interviews and hands-on processing, documented by the writer, and sent for revisions and corrections. Only the writer touches the source. Everyone else is hands-off. The new generation of tech writers is more tools-based, preferring instead to set up systems for the SMEs to supply their technical expertise directly to the source files, for editing by the writer, and technical review by the SME.
My question was, if our companies were to implement a wiki, and we publish a version of our single-source content into it, would we really want the content back after others had their turn of it? How could we enforce the modular quality of the writing and at the same time benefit from the technical expertise of the SMEs on the original source files?
I’d have a hard time trying to get SME’s to write sections for me and justify my pay. I input data from specs and they review and comment. ‘twas ever thus.
If you’re looking for a more in-depth read on this subject, I recommend Clay Shirky’s “Here Comes Everybody: The Power of Organizing Without Organizations” (Here Comes Everybody). For a shorter form, and a very entertaining read, see his “Gin, Television and Social Surplus.
Shirky contrasts the way that an organization operates (tech writing’s traditional model) with a human volunteer enterprise such as Wikipedia. Basically, he says that a business has to spend most of its energy taking care of itself: maintaining an information hierarchy through middle management, making sure that contributors are contributing to an acceptable level, that sort of thing. All familiar from Brooks’ Mythical Man-Month work.
A volunteer organization—volunteer is not quite the right word, I mean the loosely associated kind of cooperation you get from large online projects such as wikipedia—doesn’t have to worry about being effective and meeting a bottom line, so it’s not just that there are different motivators for the contributors, it’s actually a whole different model.
That sounds like a small statement, but it has widespread implications. As far as I can tell, Shirky is saying there is NO WAY to make a wikipedia-type effort work in a business environment (though I haven’t finished the book yet).
Like others, I have been trying to find a way to make a wiki work on both levels (organizational and cooperative) and Shirky’s argument seems to be, they never can. It’s not even an apples to oranges comparison, it’s apples to skateboards. That’s not to say we can’t use a wiki as a data-gathering method, but we won’t be building “project-ipedia” in-house unless completing it is our paid-for assignment. And I don’t want to get behind that until I can reconcile how the content will be managed and approved. Maybe we have to give up the idea that there is just one Official truth. :-)
I feel like there’s more possibility here, so I’m still looking, but for now I’m just trying to get my head around the implications of the differences between “orgnaizational” and “cooperative.”
Like others, I have been trying to find a way to make a wiki work on both levels (organizational and cooperative) and Shirky’s argument seems to be, they never can. It’s not even an apples to oranges comparison, it’s apples to skateboards. That’s not to say we can’t use a wiki as a data-gathering method, but we won’t be building “project-ipedia” in-house unless completing it is our paid-for assignment. And I don’t want to get behind that until I can reconcile how the content will be managed and approved. Maybe we have to give up the idea that there is just one Official truth. :-)
My co-workers returned from Philly all charged up because they found that Agilent uses a wiki for all their documentation. Strange as it seems, I too have a hard time believing that would work in practice. But you hit the nail on the head with the idea of making it a corporate responsibility for all members of a company to provide quality content. Then all it would take is an editor’s sweep for consistency, flow, organization, and voice, and the document is virtually fit to print.
I stumbled on a Sept 2007 article about Twiki - the structured wiki. I recall that was a product you recommended at one time, Tracey. I am just about ready to install the structured blogging plugin for Wordpress on my site. Structured blogging. What a concept!
To revive this thread and take it back to basics, I got a request from a friend:
“Our company’s about to undergo a major change in how we publish our material and suddenly all of our editors are going to have to learn the principles of single sourcing. (I’m the only one who even knows the phrase; all the other editors are journalists.) Do you know of any online writing workshops/courses that could help?”
I did a quick search through the Intercom archives for some “Single Sourcing 101”-type articles, but didn’t find anything that fit the bill. Would you folks have any suggestions. Thanks!
The EServer Technical Library links to quite a few single-sourcing resources from STC and other places: http://tc.eserver.org/dir/Single-Sourcing.
Having worked on a few single-sourced projects now, my advice is to establish some authoring guidelines for the team to start thinking how to structure and write their content for reuse in different contexts.
Hi Tony, Tracey,
With regards to outputing content to wiki - I agree - there are some complex problems to address. It seems wiki works best when everyone in an organization/group/team is on board. Otherwise, the content gets stale pretty quickly. I have also found wiki’s to be useful for ‘current’ content - finding previously-updated content can be hard unless authors have used specific terms that you can search on or you are pretty familiar with how the author(s) have structured the wiki content. That said, I’m intrigued to know if wiki can be used for an effective review tool for online documentation. If the Wiki>DITA flow can be figured out, the results would be pretty neat.
