just write click

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.

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.

Happy thanksgiving everyone! I have much to be grateful for. Here’s me with my son, both of us stuffed full of turkey.

Deadline extended… multiple meaning

I just learned that the Give 1 Get 1 program to purchase two XO laptops has been extended through December 31st. Hurrah!

I’ll admit it - my first thought was, good, I can delay that $400 escaping my bank account until after the holidays. But my second thought was, “Say, we can work more on the simplified user guide to get a nice PDF and even more language translations!”

Wiki writing workflow

I said I’d try to describe the workflow of wiki to Author-it. It’s pretty feeble and I really want better ideas so feel free to offer up your thoughts here.

Some history on the legacy. The file started out as a Google Document, which basically meant it had nice clean HTML code underneath and could be written on collaboratively and shared discerningly. The links to the wiki URLs were actual URLs rather than the wikitext linking code. The text contained a bit of passive voice and was more descriptive than task oriented.

Always start with task analysis

Once I read it, I did some task analysis, which is available in this published Google spreadsheet. I broke down the tasks based on whether the user was a kid, a parent, or a teacher using the XO. Then Emily Kaplan and I started re-writing the sections and adding section (or topics) based on the task analysis. First we tried writing each topic as an unpublished WordPress blog entry, thinking that we could eventually get translations done using the Worldwide Lexicon open source initiative. An interesting concept, perhaps well-matched to the spirit of the OLPC project, but we learned that maintaining a Table of Contents would be difficult, and also found that the Laptop.org folks like SJ Klein really wanted the wiki at wiki.laptop.org to be the source for all content.

Wiki as source

I completely agree with this wiki-centric approach and we have adapted. All the WordPress entries (there were less than eight of them) went into the Google doc, and then Todd Kelsey “wikified” the Google doc by saving it as Word, then using a visual basic script to convert to wikitext. We lost all the graphics placement but were able to get a wiki page going with the Google doc.

Word to Author-it…

During the same week’s time, I had taken the Word document saved from the Google document and imported it into Author-it in the instance donated by Author-it (thanks so much) on a server donated by Hostway (again, thanks) and that import worked really well with graphics and links and pretty much everything intact.

Wiki to Author-it… and back again

But this is where the wiki as source becomes difficult, right? Any changes that are made to the wiki must come over to Author-it, and that’s a manual and “think-tual” process. And I’m behind and should stop writing this blog post and go work on synching and writing more topics based on the task analysis.

Localization

As far as translations go, there were several translations done of the document when it was still in Google docs. Interestingly, many of the translators wanted Word documents to work in. Again, though, with wiki as source, I have linked to the translated files in hopes that others will pick up and wiki-fy the translations. One area I’m still learning about is whether the wiki engine has tools for the editors of translated pages to keep up with changes made to the English version and vice versa (if changes were made to the Spanish version of the wiki page, how could we incorporate those into the English version of the wiki page?)

Wikitext, wikitalk

I’m learning so much more about wikis (especially wikimedia) from this hands-on experience - such as “signing” notes with ~~~~ to get your username and a time date stamp automatically, and using “talk” pages to communicate with others on the wiki by posting notes for another user.

XO User Club in Austin

I’m also committed to starting an Austin-based XO User Club, following Robert Nagel’s lead with his excellent blog post and article in OLPC News. Let me know your thoughts here - I would like to see if we could meet at one of the Austin public libraries, probably on one Saturday a month (although we’ll be competing with soccer and other Saturday activities). We might have to play it fast and loose for a while and see what type of core group we gather. There’s a User Groups wiki page at http://wiki.laptop.org/go/XO_Giving/Users and it’s great to see where the groups are cropping up.

How to help

If you’re interested in writing more of the user guide for the laptop, all are welcome to contribute to the wiki page at http://wiki.laptop.org/go/Simplified_user_guide. Use the task analysis as your starting point if you want to start a new topic. I’m also seeking a page layout person with Word expertise to get a nice square manual that Lulu.com could easily print. Graphics to explain procedures, especially using the Activities, are always welcome over text. Join the OLPC Library mailing list where we discuss documentation and e-books for the XO.

Also, consider using the give one get one program to give the “get one” to some deserving kid in Austin, especially now that the GIG1 offer is extended. I’d buy ten of them if I could, to start the XO kids club with no “entry fee.”

Also, join us at the XO club meetings, with or without an XO, if you’d like to bring your Linux or Windows laptop and emulate Sugar, the XO’s operating system. EToys and TamTam experts are welcome.

1. Content is king. Your source content can be Word, Frame, or DITA. You can even import convert other formats such as RoboHelp to Word or Frame and go from there.
2. Formats are separate from content and can be customized.
3. Combining content is allowed and even encouraged. Mixed content is just fine.
4. There are great demos (over an hour’s worth) on the Quadralay web site.
5. ePublisher has an extendable XML adapter. This extensibility means that no matter what XML you’re putting in, ePublisher can be extended to understand it.
6. You can automate the dickens out of your output build processes and integrate with development’s version control systems and build with the Auto-mapper.
7. The WebWorks Wiki (uses MoinMoin engine if you’re wondering) has lots of information and they encourage people to contribute to it.

I’m attending as many sessions as I can at the Quadralay WebWorks User Conference - called the WebWorks RoundUp. Right now I’m listening to a great demo using WebWorks to publish Word or Frame source files to wikitext.

Start with WIF

The WebWorks wiki defines WIF as WebWorks Intermediate Format - basically their Document Type Definition. Serendipitous search engine love for WebWorks. I hadn’t realized that when you Google “WIF” you’ll find there is a lot of academic call for the Wiki Interchange Format - a lowest common denominator of wiki content exchange. WIF defines a subset of XHTML as an over-the-wire format for wiki content exchange.

Keep it simple

He’s demonstrating the concept with headings and paragraphs only, but I would imagine that ordered and unordered lists would be simple, even nested indented lists are simple enough to mark up.

No tables, and I’ll admit, they’re a nightmare to markup in wikitext, so I sure wouldn’t tackle writing the XSLT to create tables from XML to wikitext.

Graphics you could create the wikitext for the file reference, as long as you take the time to upload the graphics to the location where the wiki is expecting them.

Generate the wikitext

He’s generating wiki markup using XSLT transforms that he has already set up.

Wikitext markup is really simple, using ASCII characters such as == heading text == to mark up a heading. In this example markup, more equals signs surrounding the heading indicate a deeper nesting of headings. Two equals signs indicate a heading 2, three === indicates a heading 3. Paragraphs are often not marked up at all, making them the simplest output of all. Refer to the wikimatrix.org’s markup comparison tool for more examples.

I would have liked to see examples of links and image references created, but this was an hour demo after all.

Put wikitext into your wiki

Finally, he’s copying and pasting the marked up wikitext into his wiki. For a long article where one page is one article, this approach makes a lot of sense. I could use a tool like this for the One Laptop Per Child project, where we have a Simplified user guide all in one wiki page. Each section is editable just because the wikitext is marked up using ==section name==, which is the markup for that particular wiki (MediaWiki).

And in his keynote the following day, Ben Allums demonstrated that he could publish to the wiki itself. Now THAT is an exciting development. I’ll dig deeper into the guts of that and report back.

Scenarios for converting to wikitext

I can think of plenty of scenarios for using this conversion process. Let’s say you need a hundred page user manual put into wiki format. This type of conversion would give you a huge leg up on the pre-population of a wiki with a user guide that is already in FrameMaker or Word. I would imagine you could somehow automate the webform population. For example, use IBM’s freely available CoScriptor to record the process where you create a new wiki page, then just run the CoScriptor script and paste when needed, then run another script that renames the new wiki page.

Because you can also publish directly to the wiki, but it seems to be in a way that doesn’t touch what’s already there, this method is a great way to continually update your wiki with fresh content.

Another great use of creating wikis with a conversion process would be for API documentation, especially if you already had a large body of work in a wiki. Let’s say you’re using DITA as your source file for your API, convert new portions to wikitext.

Any other scenarios for this conversion tool?

Our team is so excited for the new Author-it version 5.0 that we invited other Austin techpubs teams over to our office to watch the US & Canada webinar. It was like a movie premiere. Okay, we’re not really that big of dorks. But we had a good time with it.

By my calculations, it was about four AM Australia time but both the presenters were troopers, even when the typed-in license key didn’t “take” during the migration portion of the demo. All of us in the room empathized with her and she smoothly avoided any delays.

I’m mostly excited about the new interface. And Australians New Zealanders say “ribbon bar” so sweetly. It’s such a nice update. I’m really looking forward to using it. The organization of styles and templates makes sense as well, and I am glad to have separation between paragraph styles and character styles.

The search bulk-ups contain the features my co-worker was looking for - search within a folder and match case or whole word. Also the search within a topic as a customizable panel pop-out is going to be highly useful. That new editor interface is especially exciting. It reminds me of XMetal’s editing environment.

We can’t wait to start trying publishing profiles. We wanted to just start clicking in the dialog boxes displayed during the demo. Their knowledge base says that eleven profiles are shipped right out of the box (mapped directly to publishing outputs). The output types I see in version 4.5 are DITA, Word, PDF, HTML, XHTML, HTML Help, Microsoft Windows Help (RTF-based), Java Help, Oracle Help, XML, and Author-it Website Manager format. Since that list adds up to eleven types, I guess there are no new outputs with this release.

While we don’t currently have a use for Author-it Xtend, I found it fascinating as a concept. Why would a techpubs department pay money to a vendor for an embedded search engine to try to encourage writers to re-use? Why not just spend that money in training (or hiring) writers to think more about topic orientation and re-usability?

My co-worker pointed out that in a translation situation, Xtend might pay for itself in one translation round. It seems so very Google-like. There’s this sliding bar for more Fuzzy matches and more Relevant matches. There’s color coding for matches. I’m automatically drawn to it like a moth to a back porch light, yet I’m not sure of the best applications for the search hits nor what problem teams should expect to solve with this functionality. Perhaps someone can tell me the best scenarios for this add-on?

We copied the Questions and Answers from the webinar, and people asked plenty of questions. Here’s just a sampling - does 5.0 run on SQL Server 2005 (yes), does it run on Windows Vista (yes), questions about the new Project Manager (purchased as a separate module but is integrated into 5.0), is the 5.0 upgrade covered by a maintenance contract (yes), can you upgrade from 4.3 to 5.0? (yes), are presentations part of 5.0 (yes), and the final question was a good comparison: Can I use the Filters (Variables) on the Publishing Profiles as I would have used conditional build tags in RoboHelp to include/exclude content from specific output types? Am I understanding this correctly? The answer: yes, that’s correct.

So, exciting new features abound and we can’t wait to get our hands on them. I’ll keep you posted on our progress.

Ah, simplicity. Elegant. Succinct. Basic. Good.

Welcome to ASI, new writer. Here are the basics:

• Write well, quickly, in the active voice and the present tense.

• Put punctuation outside the quoted material.

• Maintain gender neutrality. (”He” and “she”: bad. “They”: good.)

• Replace semicolons with periods.

• Use numerals for all numbers.

• Make cross-references target-neutral.

• Insert AIT variables.

• Publish Word documents or HTML files only.

• If it’s not here, look to The Microsoft Manual of Style for Technical Publications.