Subscribe to RSS
Posts Tagged ‘information architecture’
Can DITA train writers? Or does it require too much programming?
DITA for writers (content creators)
I just did a search on amazon.com for books for beginning technical writers and also to investigate what books are being written for our profession and for others wanting to start in our profession. I came across a book called Writing Software Documentation: A Task-Oriented Approach that suggests three categories for writing:
- writing to teach (for eager learners)
- writing to guide (for reluctant users of the product)
- writing to provide a reference (for experts who need only occasional support)
I immediately saw a connection to the three content types that DITA prescribes:
- concepts to teach understanding
- tasks to guide performance
- reference to offer facts or lists of information
Because writers have to immediately place the information they want to record into one of these three types of information, they are being trained on how to write in a task-oriented, performance-based manner, via DITA. I am especially interested in this “training” for wiki authors and talked about the idea at our recent presentation at the Central Texas DITA User Group meeting.
DITA for publishers (formatters)
Recently a few techpubs bloggers have been talking about DITA and its weaknesses, such as a lack of online help outputs, and how difficult it can be technically if you don’t already have a staff with pseudo-programming skills. Gordon Mclean writes “DITA is not the answer” and I think the question he is trying to answer is, “what is a single-sourcing tool we can use in our environment (which includes Technical Communications, Training, Pre-Sales and Marketing) with our current resources?” Instead of DITA, it looks like he’ll go with Author-it.
Since I just this past year moved from BMC, which is still moving to DITA, to a small techpubs group that uses Author-it, I can understand his reasoning and agree with his business case assessment. The toolchain for DITA is very nearly there, but often a CMS-based approach has too much overhead for small companies. It can be cost overkill when you have few topics to contain.
Scott Nesbitt followed up with his post, “DITA’s not THE answer for single sourcing.” I think he’s spot on with the analysis “it’s difficult to get good PDF or online help from DITA without extensively customizing XSL stylesheets or passing DITA source files through tools like FrameMaker, Flare, or WebWorks.” One of his commenters said something about consultants smelling blood in the water, yikes. In other words, I think he meant that XML consultants knew how much customization would be desired and can have a feeding frenzy on the potential work possibilities. My guess is that the people who have been around XML for years know that there are still basic needs for output, and their experiences have shown them that nothing that is structured is an “out of the box” experience. So much of the success depends on your content to begin with.
I’ve found the same conclusions about the output in my experience. When you dig into single sourcing, be it with DITA or another tool (Madcap Flare, Author-it, FrameMaker, RoboHelp, and the Adobe Technical Communication Suite) the real business-case killer seems to still be, where can I get pretty PDFs that are formatted just as I like them? With DITA, one answer is to go get the Mekon FrameMaker plug-in for the DITA Open Toolkit. No XSLT-FO knowledge required.
People love their tools to get their pretty PDFs or sleek online help systems. Plus, so many of the employers out there have a lot of content that looks pretty nice already in a specific tool. The legacy documentation may be one reason why hasn’t DITA helped our industry get away from tool love. Tech writers and their employers fall in love with tools. I’m not saying Gordon or Scott are tool lovers, but certainly some people they’re hiring will be. There is probably also an element of “if it ain’t broke, don’t fix it.”
DITA for all?
Sarah O’Keefe has a thought-provoking analogy in her comments on her post signed “DITA Dissident.” The analogy is that creating desserts using a frozen pie crust is one method of getting results. If a pretty PDF is your ultimate dessert, then for some, DITA is a bag of flour, meaning you’d better be a skilled baker if you’re going to use it for the best pie (PDF) ever. For others, DITA is a frozen pie crust that makes a perfectly good cherry pie (PDF) or apple pie (plain HTML) or chocolate creme pie (Eclipse help). Although isn’t the filling the content and the pie crust the DITA map?
Their conversation first started with Eliot Kimber discussing DITA’s use for narrative documents. Alan Porter talks about DITA use for narrative writing as well, but in a different line of thought in his post, Is DITA Just a Story?
All the posts I’ve linked to are enjoyable for me to read and to point to and to think about. I’ve read it before, and I’ll say it again, I believe along with others that DITA has the potential to transform our industry. Just last night I said to the San Antonio STC group, today we all speak HTML tags pretty fluently. In ten years, will we all speak DITA tags just as fluently? “I wrote the shortdesc according to the guidelines and it works for the topic, but I am not sure if my conref target is going to be there every time. I guess I should rewrite the concept topic.” Heed the warnings and experiences of others before making the leap to topic-oriented single-sourcing or your expectations and those of your customers may not be met.
Q and A about Author-it and DITA - guest post from Mike Stockman
I read this recent conversation on the author-it-users Yahoo Group with interest. I haven’t had a need to author DITA topics with Author-it, so I have to rely on others for information on how it works. With Mike Stockman’s and Tony Watkin’s permission, I’ve written their Q&A as a blog entry.
Tony: What are your experiences with using Author-it for DITA output?
Mike: The DITA output is partial. That is, they don’t support a lot of DITA features, so that most table definitions are not passed through, bookmaps aren’t supported (although ditamaps are), reflinks aren’t supported, syntax diagrams aren’t supported, and so on. However, it’s definitely usable, so that AIT puts out the four DITA topic types (task, reference, concept, and base) properly structured, index entries are supported, tables and images are handles correctly, and so on. The best test would be to publish to DITA and see whether the results are what you’re expecting.
Tony: Is there a mechanism provided by AuthorIT for being able to search within the DITA XML generated output afterwards from within the browser when accessing the DITA output directly from the browser (i.e. not via AuthorIT)?
Mike: There is no mechanism provided by AIT for viewing DITA output. Once you have the DITA output, you can either view the XML code, or transform it into something more viewable, such as XHTML or PDF. Grab the DITA Open Toolkit, available at <http://dita-ot.sourceforge.net> for all of the tools you’ll need to transform the DITA into something else.
Tony: Also, does AuthorIT just output XML when publishing DITA or does it also produce corresponding XHTML?
Mike: AuthorIT publishes DITA by first publishing to XHTML, and then transforming that to DITA. It does not, however, leave the corresponding XHTML behind, so you can’t view it. Your choices for viewing XHTML would be to either publish from AuthorIT to XHTML directly, or transform the DITA to XHTML.
Mike’s final comments
AuthorIT’s DITA is not a fully-developed DITA solution, so don’t expect it to be. Instead, AuthorIT’s DITA output is great when you have a need for single-sourced output to multiple formats, such as if you needed Word, XHTML, *and* DITA. Where I work, for example, we use AuthorIT’s Word output for our printed docs and PDF, and use the DITA output to create our online help. If you need the advanced features of DITA that AuthorIT doesn’t support, I’d suggest going to an all-DITA authoring environment and avoid AuthorIT altogether.
Something old, something new - design patterns
I’m feeling a little late to the party of patterns that I’ve been reading about lately, but after attending Michael Hughes’ STC webinar presentation “Pattern Language as a Workshop Management Tool” where we saw patterns for user assistance, and we were really intrigued by an internal wiki page he pulled up giving DITA patterns to IBM info developers. Turns out, he had read my wiki article from STC Intercom and has been working on that internal wiki for a while.
His article, “A Pattern Language for User Assistance” is an excellent read. He introduces the idea that you can use a template to describe where a user might be triggered to seek assistance and then describe how to contextually place assistance and offer wireframe models for others to follow when implementing user assistance. A pattern template can be as simple as “here’s the context, here’s the solution, let’s name it as the How-to pattern.” Michael Hughes’ pattern template is slightly more complex but context and solution are the basic elements.
I went on the hunt for more examples of User Assistance Patterns. I found both JoAnn Hackos’ article “Design Patterns: Creating Consistent Information Designs for Print and Web and the DITA design patterns article on DeveloperWorks. Both are great article, and as a co-worker said, the guys at IBM are doing some of the most advanced information architecture and design available today. And even two and three years ago I might add.
Our group discussed how we’d really like to ensure that our user assistance (UA) patterns follow DITA’s patterns – because in Austin, more and more writers that we would potentially hire will be familiar with DITA. So if our UA patterns already match DITA’s patterns, it’s that much easier to get a new writer up and running.
Don Day said that there is a new Help workgroup with the OASIS DITA Technical Committee that will specify patterns for organizing UA sets. This type of work would help immensely with merged help sets even within one company, not to mention plug-ins for open source software projects and the like.
Don also alerted me to the DITA Troubleshooting plugin contributed by an info dev team at IBM. I plan to investigate further because that work would give any information architect a huge head start on designing topics for troubleshooting. An excellent reusable pattern indeed. They even have 12 role-based elements for use in responses when there is a problem - I imagine the use is for writing different instructions for sysadmins who might respond differently than end-users - but I’d need to really study the implementation.
Bob Doyle has mentioned patterns as well, in this Best Practices Reporting with DITA post. He sees the helpfulness of Object Oriented Design Patterns - which are the famous example among programmers - and he proposes a design patterns domain. Very interesting idea.
So while in some ways I’m late to the pattern party, in other ways, many opportunities still abound for reusable patterns in user assistance and other design patterns for technical communication that can be DITA-based. The ultimate vision - one set of patterns that all technical communicators can use and that these patterns plug in with each other with few seams. (Sewing metaphors should be allowed. This is about patterns, after all.)
Serendipitous trips through the river of information
Anne Zelenka has once again nailed down the idea of how to work in a new world where there are far too many sources of information and no way to use technology to help you sift through that information. So you get on your raft and float along the current, and along the way you find the information you need to get a job done.
In The Future of Ignoring Things on Internet Evolution, Cory Doctorow says “I’ve come to grips with this — with acquiring information on a probabilistic basis, instead of the old, deterministic, cover-to-cover approach I learned in the offline world.”
One of the commenters on Cory’s article talks about navigation, saying “We need a sensible, extraordinary navigational system which helps the things we care about at the moment rise to the surface.” How amazing would your help system be if you could apply this technology to your product’s help?
My own journey - searching information
As for me, I am coming to terms with the idea that I’ll stumble upon useful information. But I tend to think I’m a pretty darn good researcher and that my Google Fu is strong, enabling me to find the best relevancy and authority in my information seeking. The more I travel on the river of information, though, the more I’ve come to appreciate the serendipitous discoveries.
My occupation - supplying information
Since as a technical writer, I write the loads of information that others need to sift through (or travel upon, choose your metaphor), this mind shift seems very important to follow. While Cory and Anne are miles ahead of most of the audience of the product I work on for my day job at ASI, my work on the OLPC project has a very different audience and that audience might be closer to Cory and Anne in their ability and desire to find information probabilistically. So for the OLPC project, documentation in a wiki seems appropriate. For ASI, only subsets of the overall audience might benefit from a wiki, such as the technical implementers using the Software Development Kit.
So, back to the basics it is - consider your audience while creating that flow of information. And keep an eye out for that extraordinary navigational system.
An example of serendipity in information finding
And now for the storytelling portion of this blog post. I often write blog entries and leave them in draft form for a while. This very post happened to be in draft form while I wrote and published my recent Wikislices entry. Sheece Baghdadi, who is a technical writer for Webaroo, saw my link to Webaroo, came to my blog, and posted a comment on my entry. I read Sheece’s comment, and I followed the link to Sheece’s blog, where the current post is about searchradar.webaroo.com, which attempts to address the very problem that “searching is easy but finding is hard.” With the Search Radar FireFox plug-in, additional search queries are suggested to you in a column to the right while using Yahoo or Google. I immediately saw a connection to this post, which was still in draft form. So I added this story to the post. What a journey.
This type of suggested searches might be helpful to our end-users since the vocabulary varies widely for non-profits, organizations, or churches using our technology. Other searches might suggest a serendipitous path for our users to take to obtain the information they need. Take a look at the tag cloud that offers other search possibilities when you search for “agile” at searchradar.webaroo.com.
Blogs are a great way to find information probabilistically. I think there are other applications of technology that can help our end-users find information probabilistically as well, if they are ready for it.
Time to change the name of my talk.bmc blog
I’ve been blogging since last September, believe it or not, with almost 75 posts to show for it. After talking it over with my peers and the web team and studying the content including the categories and trends for my content, I’ve decided to change the name of this blog to “Exploring Information Design and Development.”
My Bloglines subscription already picked it up, which is quite cool. It is probably time to re-import the talkbmc.opml file to get feeds for the new additions. Welcome all!
