Subscribe to RSS
Posts Tagged ‘DITA Storm’
DITA and wiki - w/ho/w will (we/you) write
I received an excellent question from a reader about his eagerness to use wikis for his product’s doc set, but he came across conflicts and issues when he questioned the practicality of maintaining a wiki for his large set of documentation. Here’s Paul’s well-phrased request for information.
I am considering using a wiki for documentation projects, but have been coming across some showstopper issues. Here is the story:
Our documentation set is large. We only want to maintain one set of files. Therefore, any changes in the wiki would need to be automatically synched with the source files.
The obvious suggestion is “just make the wiki your source files.” However, it is not as simple as that, for a few reasons.
- First of all, we need to generate attractive offline documentation in online help format, viewable across several operating systems. No wiki enables an elegant way of doing that.
- Secondly, we have a bunch of conditional text–our existing documentation comes in six different versions. I have not found a good way to integrate the different conditional tags into a wiki, while maintaining it in both our sources and the offline output files.
- Finally, wikis almost by nature do not support DITA. Wikis are designed to be simple and easy to understand. However, that approach negates many of the advantages of structured writing.
For these reasons, I currently see wikis primarily as a collaboration tool. But they do not have the features necessary for complex technical documentation.
Do you have ideas for how we could get around these issues?
Oddly enough, on this particular day, another reader wrote in about similar issues with wikis, but they have started to overcome them. He listed the issues succinctly, saying:
I’d say that there is quite an art to creating wiki doc from a couple of perspectives:
* conversion
* building out the infrastructure
* look-and-feel issues
* style issues
* review issues
* basic editing issues
Even with all these issues — 
— however, the immediateness of the experience, the ease associated with making changes and the creation of links and containers, and the modern look and feel really make wikis a fascinating competitor with other, much different technologies. How many other industries move off in such opposite directions (wikis vs. dita)? It’s sort of like trying to figure out whether cars should run on gas or steam!
The CEO of Confluence came through a few weeks ago. He was pointing out to the following as an example of a company that had developed wiki doc:
http://www.gigaspaces.com/wiki/dashboard.action
Here are two more you might find interesting if you don’t already know about them:
http://docs.codehaus.org/display/GROOVY/Documentation
http://www.aptana.com/docs/index.php/Main_Page
And here’s the part that is amazing to me - in a follow up email, Paul answered some of his own questions and said that the gigaspaces.com wiki is one wiki he is investigating further. For example, by talking to one of the writers, he learned that their wiki has 1300 pages, and reuses many pages through the [include] command or transclusion, which is the inclusion of part of a document into another document by reference. My original response to Paul talked about DITA as source files and wiki as an output from those source files. I learned that Robohelp does something like that, with source files and wiki as output, and this blog post mentions round-tripping the content back to Robohelp.
Naturally, I have some ideas about DITA and wikis. My post about DITA Storm built into a custom wiki describes a hybrid approach, with DITA files as the source and editable pages. Paul takes that idea one step further, saying that you could have the internal technical writers see a DITA editor interface to the wiki, but have end-users write doc in a simplified editor with fewer tags. I like that idea.
There’s also the possibility of a transform from DITA to wikitext. A search on the dita-ot-developer list on sourceforge.net revealed that Deborah Pickett was writing such a thing for her employer last April. I emailed her and she generously gave me her XSLT source files, but said that she gave it up when she found that “The whitespace rules for wikimedia meant that anything fancy would end up being better written in wikimedia’s pretend HTML format anyway.” Hm. I haven’t tried the transform yet myself. Bob Doyle has done a lot of DITA to WikiMedia transformation to pre-seed the ditawiki.org with content, and he says “The Perl script for conversion to MediaWiki is publicly available at http://www.jtidy.de/conv. It has a major flaw in that it does not convert URLs to hyperlinks.” Again, I’d need to try it myself to see whether that approach would work and if the technology scripting is worth the effort.
Now, for everyone pondering wikis and DITA, an absolute must read is this great article by Paul Prescod, The Convergence of Structure and Chaos. Not that it offers practical solutions (although he hints at some at the very end), but it maps DITA concepts to wiki concepts.
I’ve also been noticing that people are trying to automate getting content from their support forums into wikis… Check out this poor intern’s daunting task: http://ask.metafilter.com/62679/Automated-Media-Wiki-Page-Creation.
I guess to answer my own question about where wikis fit in tech doc, I currently see wikis as supplemental, not source doc from which to make other things. I probably lean towards seeing a wiki is another output from perhaps DITA source. Sure, there would have to be a loopback mechanism to get the contributed parts of a wiki back to the source files, and I’m not sure how automated that could be. But, I would love it if vendors could convince me otherwise, and frankly, I keep hearing about Confluence and their examples are compelling.
So I share with you these side conversations I’m having in hopes that the information here helps others in their quest to offer wikis to their end-users. Users, write the manuals. But make sure us writers get to meet our objectives as well.
As a final departing thought, I share the machine is us/ing us video, containing the best description of Web 2.0 and new media I’ve seen to date, created by a cultural anthropologist. It’s about five minutes long, and a thought provoking piece.
One of the questions in it that stuck in my mind was the question at about 3:00 minutes, “Who will organize all this data?” And the typed and re-typed answers after a screencast or demo of del.icio.us:
We will.
You will.
Getting Started with DITA
I have gotten two similar questions about getting started with DITA in the time span of about two weeks, so I thought I’d borrow from some of my answers as a write-up for a blog post. One person wants to ditch her Adobe toolset in frustration and try out some DITA workflows with all free tools. The other is a lone writer in a small shop and wants to find out more about DITA and see if it might work well in her Agile development environment. While I’m a huge DITA advocate and see many ways that DITA can help with many doc goals, I don’t think that DITA has all the answers necessarily. Topic-based authoring with just concept, task, and reference types is a different mind set for both writing and publishing. But, you could certainly put together a toolkit of freebies with DITA to try it on for size. So here are some starting points.
Get very familiar with topic-oriented writing
Without some up-front information architecture and design where you really analyze your documentation needs, and figure out what task, concept, and reference means for your body of work, DITA won’t help you. Transforming legacy information into topics may or may not be a worthwhile effort so some up front analysis will help you.
Bare minimum tool set to “do” DITA
You’ll need the DITA Open Toolkit, available at http://sourceforge.net/project/showfiles.php?group_id=132728. Here are direct links for the 1.3 package that you just download and unpackage on your hard drive. Windows zip Linux tarball
These full packages of the DITA Open Toolkit contain all the sub-tools that you need for full evaluation from authoring to building output. Most of these tools require the Java Platform, so, Java is a prerequisite to using the DITA Open Toolkit. Download and install the Java Platform Standard Edition (SE) 5.0, available at http://java.sun.com/j2se/index.jsp.
Ant 1.6.5 runs automatic builds on your DITA maps, and the DITA Open Toolkit gives you ant scripts for builds already.
Xalan-J 2.6 is an XSLT processor which is required to run the transforms.
FOP 0.20.5 is needed for PDF output. (Note: For compiled HTML help (CHM) you’ll need the HTML Help Workshop, which isn’t included in the Open toolkit, but most help authors will already have this installed.)
ICU4J 3.3.4 is included for improved NLS-enabled index sorting.
Apache Catalog Resolver 1.1 is a standard XML catalog mechanism.
Plus, the newest full package (1.3) contains a startcmd batch file in the root folder that you can use to set up your environment each time you run the DITA Open Toolkit. Considering what headaches I had just with environment variables in Windows, I am greatly appreciative of this little batch file.
If you want to first just look at topics and create some output before authoring anything of your own, look at the EvaluateOT.html file in the root directory of your DITA Open Toolkit install. Double-click the startcmd.bat file, then type ant samples.web -f build_demo.xml at the command line and you will have your first set of DITA output in a newly-created \out folder in your DITA Open Toolkit installation folder.
When you want to create your own topics and maps, you’ll need an XML editor. While you can certainly edit DITA XML in Notepad, you’re going to want a validating XML editor for serious authoring and evaluation. See my suggestions next.
DITA XML Editors
Previously I posted my notes from Don Day’s talk at the Central Texas DITA User’s Group about evaluating DITA editors: http://talk.bmc.com/blogs/blog-gentle/anne-gentle/dita-editor-eval. Now, the next step for me is to start naming names. Let me be clear, though, since I’ve been on maternity leave for the last six months or so, I haven’t been seriously evaluating XML editors for BMC. Others are doing that and I’ll be happy to use whatever they recommend for our environment. But, for my friends who have been asking me about DITA, let’s break this evaluation into free and not-so-free. Note: nearly all enterprise-level XML editors have 30-day trials, but it’s tough to get enough done in a 30-day evaluation of DITA and the XML editor if you’re just starting out with topics and DITA.
Awareness of DITA is not always an easy achievement, apparently, and when you’re new to DITA, it’s tough to evaluate “DITA aware.” So I guess you just need to trust others when they say an editor is a DITA aware editor.
Free XML editors
XML Copy Editor – this open source project has an XML editor that claims to support DITA. https://sourceforge.net/projects/xml-copy-editor/
DITA Storm – this is a free web-based DITA editor. You can either install it yourself if you have a web server, or try out the ditausers.org online web-based editor for free (use the coupon code BETA) during the evaluation period.
Enterprise-level XML editors (with 30-day free trials)
I believe that you should convince your manager you need this level of editor if you’re serious about writing DITA topics for end-user doc.
Bob Doyle has done an excellent job of evaluating XML editors in this article, X Marks the Spot: Let’s Take Today’s XML Content-Creation Tools for a Spin, complete with tables of prices, platforms, support info, all the specs you’d need to evaluate a tool for your environment. The ones I have installed and tried are: Adobe FrameMaker ($799), Arbortext Editor ($695), XMetaL Author DITA Edition ($895), and Syntext Serna ($195). You would have to determine what’s right for your particular environment and preferences.
What to do to start writing DITA topics
Open your XML editor and start with either a concept, task, or reference topic type. Or even start with a topic to begin with. Write some content, and validate it as you go. Once you get a handful of topics, make a DITA map either using the code in an XML editor or using a DITA Map editor like the Task Modeler available as an Eclipse plug-in.
What to do to get output from your DITA topics
You can modify the ant scripts provided with the DITA Open Toolkit for your own builds. I was able to do a few ant scripts just based on the template files and examples the toolkit provides. I used the “ant/ sample_htmlhelp.xml” template to make this build file for my map file named processfile.ditamap on Windows. Edited: to link to the sample build file code instead of posting it here because apparently our DIV layout doesn’t like wide-width PRE areas in the middle column.
Nice-to-have tools for anything beyond just evaluation
You’ll want to automate building output with Ant. The example build file above gives you a start, and there are plenty of templates provided in the Toolkit.
Once you think about enterprise publishing, reusing topics across groups, and so on, you’ll want to use a Content Management System. I think CMS tools for DITA is an entirely different topic that deserves more research so I won’t say more than that yet. To get started on larger doc sets without a CMS, use a logical folder structure and defined file naming conventions, then use the OS search tools to look for metadata within topics.
A DITA map editor that either integrates with the CMS or the free Task Modeler from IBM has a really good visual method for editing DITA maps.
More reading
I like the Introduction to DITA: A User Guide to the Darwin Information Typing Architecture book available here.
The DITA Open Toolkit User Guide and Reference is very useful as well, and free.
Bob Doyle, an active member of the Boston DITA User’s Group, also has a helpful article in the E Content Magazine column, I Column Like I CM: Getting Started with DITA.
Use Don Day’s evaluation heuristic for editors if you want to do a full-blown evaluation for your preferences in an authoring tool.
Everyone must read Scott Abel’s article, 10 DITA Lessons Learned From the Trenches on the Content Wrangler when evaluating DITA for their doc needs.
Anyway, once you get very far with the DITA Open Toolkit you might fall back in love with the Adobe toolkit. I’d love to hear just how far you get and whether you fall in love.
Checking out the new DITA Users website
I was looking at DITA Storm, the web-based DITA editor, for a side project today and came across a link touting “comprehensive project-level DITA authoring and publishing experience.” I’m pretty excited about this discovery — it’s ditausers.org, a place where I can try out the web-based DITA editor on a hosted web server. And, it’s free membership right now with reasonable rates later. The coupon code is BETA, just go through the checkout system and use Coupon as your method of payment. Nifty!
As for my dabblings with DITA Storm itself, I couldn’t convince my home system administrator (my husband) to help me install it on our webserver at home. Our Apache installation would have to be upgraded (one method of implementing DITA Storm needs an Apache Web Server extension that includes PHP with XSL such as Sablotron) and I don’t blame him for turning down that work request. I didn’t want to do the upgrade myself either. DITA Users has the right idea of installing the web server for you if you just want to author and publish DITA with little backend work yourself.
DITA Storm always gets me thinking about what’s next for web-browser editors and DITA. I wonder if a concept of a DITA audit is ready for prime time? You know how you can upload and validate your HTML documents to test forW3C Recommendations compliance, or 508 accessibility problems, such as the W3C HTML Validation Service and others like it (see this list). I think that some day writers might want to upload their DITA marked up documents to test for best practices in tagging for their topics, especially for task. I believe that IBM has CSS files that automatically check on how well “typed” certain content is after going through their migration tool. For example, are ordered lists in a generic topic and should be re-written as tasks with <step><cmd> elements? Is a validation step the next thing for making sure you’re using DITA to its fullest potential?
I plan to put the feed for the DITA Users Progress blog in my feed reader list. Thanks for the free beta membership, guys!
A web-form based DITA editor
Written with just HTML, Javascript, DOM, and CSS, as far as I can tell, DITA Storm is a product that enables web-form-based DITA topic authoring and display. Go check it out, their web site has a lot more content now and you can even request a copy with which to play.
As my help infrastructure buddy said, “This is so cool I think I’m going to freak out like this kid. Nintendo Sixty-FOOOOOOOOOOUR” Yep, it’s Friday, so yep, it’s a video link. Just go watch it, and get a good laugh.
I’m imagining that you could do several things with a web-based DITA editor (and topic styler). One thing would be a DITA-based wiki, where you author directly using DITA topics rather than some cryptic ASCII codes for headings and bulleted lists and so forth. End users don’t have to know DITA to enter content, either. Although I do think you’d want to also be able to copy and paste content from existing DITA topics, and I’m not sure how you’d do that (maybe there’s a “view XML code” feature in the works?). Although you can just link right to the XML topic from within the HTML page, which would be nifty for DITA topics you already had waiting in the wings.
According to the web site, “The prototype version 0.3 of DITA Storm supports following DITA elements: topic, title, shortdesc, body, section, title, note, lq, q, fn, related-links, link, linktext, desc, p, b, i, u, tt, sup, sub, task, taskbody, context, result, steps, step, cmd, stepresult.” So it is a subset of DITA so far (others are subsetting DITA but it’s not really DITA once you subset it and you can’t import DITA-compliant content later into your subsetted set. Whew.).
Another idea for using DITA Storm for end-user doc might be to build your context-sensitive help system right in with your web interface product. I suppose this idea would work only if you can lock down the content at a certain point. But the stylizing with CSS is very promising and really lets you do anything you want with the content. The stylized examples are really nice looking, such as a stylized task topic and a stylized basic topic.
And, my pet idea would also be to use DITA Storm to write blog entries. Entering blog posts in a structured language like XML would work right in with the microformatting concept. Build the next blogger.com site using DITA Storm.
This type of product in my estimation has the potential to be the next Writely, stealing from the desktop publishing user base with the beauty and simplicity of a web editor that just gets the job done. Yes, it’s another way of writing, but a nifty little tool that could help your content do some interesting cartwheels.
