Retail therapy for tech comm (and I don’t mean shopping)
“She’s stupid.”
That’s what a shopper recently said about a coworker’s daughter, who is working a part-time retail job.
Assessing DITA as a foundation for XML implementation
The Darwin Information Typing Architecture (DITA) is being positioned as the solution for XML-based technical content. Is DITA right for you?
This white paper describes the potential business advantages of DITA, provides a high-level overview of DITA’s most important features, and then discusses how you can decide whether to develop a DITA-based XML implementation.
Lost in translation (and in my brain)
Last night, a bit of spam managed to worm its way through the filters on a personal email account, and I have to admit I glanced at the content while scanning previews of messages. That’s when I spotted a paragraph that really jumped out at me:
They have good management systems, product quality inspection system. And international speedboat (EMS) is the door – door accurate! Soon!
My thought process was, What’s up with the international speedboats? And why are emergency medical services (EMS) using these speedboats? I knew that the person who wrote the content was likely not a native English speaker, but I could not figure out what the writer was trying to communicate.
This morning, I finally realized what the message was trying to say: the company uses EMS worldwide delivery services for prompt and accurate delivery to my door. My brain must not have been firing on all cylinders last night when I thought EMS meant “emergency medical services.”
I don’t think I’ve ever spent as much time thinking about a company’s marketing message, but my thoughts weren’t about using the company’s services–I was merely trying to comprehend the message itself. That’s not what the company intended, I’m sure.
Marketing for a global audience–particularly one that associates EMS with “emergency medical services”–is not an easy thing!
Flare 5 DITA feature review (Part 1: Overview and map files)
[Disclosure: Scriptorium is a Certified Flare Instructor.]
[Full disclosure: We’re also an Adobe Authorized Training Center, a JustSystems Services Partner, a founding member of TechComm Alliance, a North Carolina corporation, and a woman-owned business. Dog people outnumber cat people in our office. Can I start my post now?]
These days, most of our work uses XML and/or DITA as foundational technologies. As a result, our interest in help authoring tools such as Flare and RoboHelp has been muted. However, with the release of Flare 5, MadCap has added support for DITA. This review looks at the DITA features in the new product. (If you’re looking for a discussion of all the new features, I suggest you wander over to Paul Pehrson’s review. You might also read the official MadCap press release.)
The initial coverage reminds me a bit of this:
(My web site stats prove that you people are suckers for video. Also, I highly recommend TubeChop for extracting a portion of a YouTube video.)
Let’s take a look at the most important Flare/DITA integration pieces.
New output possibilities
After importing DITA content into Flare, you can publish to any of the output formats that Flare supports. Most important, in my opinion, is the option to publish cross-browser, cross-platform HTML-based help (“web help”) because the DITA Open Toolkit does not provide this output. We have created web help systems by customizing the Open Toolkit output, and that approach does make sense in certain situations, but the option to publish through Flare is appealing for several reasons:
- Flare provides a default template for web help output (actually, three of them: WebHelp, WebHelp Plus, and WebHelp AIR)
- Customizing Flare output is easier than configuring the Open Toolkit
I took some DITA files, opened them in Flare, made some minimal formatting changes, and published to WebHelp. The result is shown here:
Not bad at all for 10 minutes’ work. I added the owl logo and scriptorium.com in the header, changed the default font to sans-serif, and made the heading purple. Tweaking CSS in Flare’s visual editor is straightforward, and changes automatically cascade (sorry) across all the project files.
Ease of configuration
Flare wins. Next topic. (Don’t believe me? Read the DITA Open Toolkit User Guide — actually, just skim the table of contents.)
Language support
The Open Toolkit wins on volume and for right-to-left languages; Flare wins on easy configuration (I’m detecting a theme here.)
Out of the box, both Flare and the Open Toolkit provide strings (that is, localized output for interface elements such as the “Table of Contents” label) for simplified and traditional Chinese, Danish, Dutch, English, Finnish, French, German, Italian, Japanese, Korean, Norwegian, Portugese, Spanish, Swedish, and Thai (I have omitted variations such as Canadian French).
Beyond that, we have the following:
- Right-to-left language support: Only in the Open Toolkit
- Language strings provided by the Open Toolkit but not by Flare: Arabic, Belarusian, Bulgarian, Catalan, Czech, Greek, Estonian, Hebrew, Croatian, Hungarian, Icelandic, Latvian, Lithuanian, Macedonian, Polish, Romanian, Russian, Slovak, Slovenian, Serbian, Turkish, and Ukrainian
- Ease of adding support for a new language: Flare wins. In the Open Toolkit, you modify an XML file; in Flare, you use the Language Skin Editor (although it looks as though you could choose to modify the resource file directory directly if you really wanted to)
Thus, if you need Hebrew or Arabic publishing, you can’t use Flare. The Open Toolkit also provides default support for more languages.
Map files
I imported a map file into Flare and published. Then, I changed the map file to include a simple nested ditamap. Here is what I found:
- Flare recognized the map file and the nested map file and built TOC files in Flare with the correct relationships.
- Inexplicably, the nested map file was designated the primary TOC. I speculate that this might be because the nested map file was first in alphabetical order. I changed the parent map file to be the primary TOC to fix this. I don’t know what would happen for a more complex set of maps, but I am concerned.
- Flare inserted an extra layer into the output TOC where the nested map is found.
- The titles generated in the TOC are different in Flare than they are through the DITA Open Toolkit (see below).
I generated the output for my map file (the nested map is the “The decision to implement” section in this screen shot) through the DITA Open Toolkit and got the following XHTML output:
Then, I imported the same map file into Flare, generated WebHelp, and got the following TOC output:
Notice that:
-
- The TOC text is different (!!). The DITA Open Toolkit uses the text of the topic titles from inside the topic files. Flare uses the text of the @navtitle attribute in the map file. My topic titles and @navtitles don’t match because I created the map file, then changed a bunch of topic titles. The map file didn’t keep up with the new titles (because it doesn’t matter in the Open Toolkit), but it appears to matter for Flare. The entry in the map file for the first item is:
<topicref href="introduction.xml" navtitle="Introduction" type="topic">
Flare picks up the “Introduction” from the navtitle attribute.
Inside the file, you find:
<title>Executive summary</title>
The Open Toolkit uses the content of the title element from inside the file.
- The Implementation section has added an extra layer in the Flare output. It appears that nesting a map file results in an extra level of hierarchy.
The inconsistency between the two implementations is annoying.
In part 2 of this review (coming soon), I’ll look at cross-references, reltables, conrefs, specialization, and conditional processing.
Top five reasons to like XMetal and OXygen
by Sheila Loring
Full disclosure: We’re an XMetaL Services Provider and have no particular affiliation with oXygen.
I’m in the fortunate situation of having access to both XMetaL 5.5 and oXygen 9.3. Both are excellent XML editors for different reasons. I’d hate for Scriptorium to make me choose one over the other.
From the viewpoint of authoring XML and XSLT, here are my top five features of both editors:
oXygen
- Apply XSLT on the fly: You can associate an XML file with an XSLT and transform the XML within oXygen. Goodbye, command line! XMetaL will convert the document to a selected output format. You don’t choose the XSLT–it hasn’t been a big concern for me.
- Indented code: The pretty-print option makes working with code so easy. You can set oXygen to do this automatically when you open a file or on demand. The result is code indented according to the structure. XMetaL doesn’t have pretty print.
- Autocompleting tags:
As you type an element, oXygen pops up a list of elements beginning with the typed string. You press Enter when you find the right tag, and the end tag is inserted for you. The valid attributes at any particular point are also shown in a drop-down list. XMetaL doesn’t have autocompleting tags. - Find/replace in one or more documents: I’ve often needed to search and replace strings in an entire directory. In XMetaL, you can only find and replace in the current document.
- Comparing two documents or directories: Compare files by content or timestamp. In a directory, you can even filter by type so only XML files, for example, are compared. XMetaL doesn’t offer this feature.
XMetaL
- Auto-tagging content: You can copy and paste content from an unstructured document (a web page, for example), and XMetaL automatically wraps the content in elements. Even tables and lists are wrapped correctly. This can be handy if you have a few documents to convert. In oXygen, the content is pasted as plain text.
- Auto-assignment of ID attributes: Never worry about coming up with unique IDs. XMetaL will assign them to the types of elements you select. Warning: The strings are quite long, as in “topic_BBEC2A36C97A4CADB130784380036FD6.” oXygen only inserts IDs on the top-level element but full support will be added in version 10.3.
- Auto-insertion of basic elements: When you create a document, XMetaL inserts placeholders for elements such as title, shordesc, body, and p. It’s a small convenience. oXygen will also insert elements if you have Content Completion selected in the Preferences.
- WYSIWYG view of tables: The table is displayed as you’d see it in a Word or FrameMaker document. In oXygen, all you see are the table element tags.
- Reader-friendly tag view: The tags are a bit easier to read in XMetaL than oXygen. In XMetaL, the opening and closing tags are displayed on one line when possible.
This feature saves space on the page and makes the document easier to read in tag view. For example, you might have a short sentence wrapped in p tags. In XMetal, the p tags are displayed on the same line. In oXygen, the p tags are always on separate lines. This is another convenience that doesn’t sound like a big deal, but it really makes a difference while you’re authoring.
oXygen and XMetal have so many other strengths. I’ve just chosen my top five features.
What I’d like to see in XMetaL: The ability to indent code, the ability to drag and drop topics in the map editor.
What’s I’d like to see in oXygen: The ability to view a table–lines and all–in the WYSIWYG view instead of just the element tags.
So how do I choose which editor to use at a particular moment? When I’m casually authoring in XML, I choose XMetaL for all of reasons you read above. The WYSIWYG view is more user-friendly to me. But when I’m writing XSLT or just want to get at the code of an XML document, oXygen is my choice.
Get the scoop on oXygen from http://oxygenxml.com. Read more about XMetaL at http://na.justsystems.com/index.php.
Update 6/15/09:
I’m thrilled to report that two deficiencies I reported in oXygen 9 are now supported in the latest version of oXygen — 10.2.
- In Author view, tables are now displayed in WYSIWYG format. Just like in your favorite word processor, you can drag and drop column rulings to resize columns. After you resize columns, the colwidth attribute in the colspec element is updated automatically. This is much easier than manually editing the colwidth.
- In Author view, the tags are now displayed on one line when possible. Before, the tags were always on separate lines from the content.
Two more reasons to love oXygen!
Our first experience with print on demand (POD)
It’s been a little over a month since we released the third edition of Technical Writing 101. The downloadable PDF version is the primary format for the new edition, and we’ve seen more sales from outside the U.S. because downloads eliminate shipping costs and delays.
Selling Technical Writing 101 as a PDF file has made the book readily available to a wider audience (and at a cheaper price of $20, too). However, we know that a lot of people still like to read printed books, so we wanted to offer printed copies—but without the expense of printing books, storing them, and shipping them out.
We have published several books over the past nine years, and declining revenue from books made it difficult for us to justify spending thousands of dollars to do an offset print run of 1000+ copies of Technical Writing 101 and then pay the added expense of preparing individual books for shipment as they are ordered. Storage has also been a problem: we have only so much space for storing books in our office, and we didn’t want to spend money on climate-controlled storage for inventory. (Book bindings would melt and warp without air conditioning during our hot, humid summers here in North Carolina.) For us, the logical solution was print on demand (POD): when a buyer orders the book, a publishing company prints a copy using a digital printing process and then ships it.
We chose Lulu.com for our first experiment with POD, and so far, we have been happy with the quality of the books from there. We are still exploring our options with POD and may try some other companies’ services in the future, but based on our experience so far, I can offer two pieces of advice:
- Follow the specs and templates provided by the printer, and consider allowing even a bit more wiggle room for interior margins. The first test book I printed had text running too close to the binding, so I made some adjustments to add more room for the interior margins before we sold the book to the public.
- Look at the page sizes offered by the different POD publishers before choosing a size. If you choose a page size that multiple POD publishers support, you’ll have more flexibility in using another publisher’s services in the future, particularly if they offer other services (distribution, etc.) that better suit your needs. Also, ensure the page size you choose is supported when printing occurs in a country other than your own; some publishers have facilities and partners in multiple countries. In an attempt to minimize the amount of production work for the third edition, I chose a page size for Technical Writing 101 that was the closest match to the footprint of the previous edition’s layout. However, I likely would have chosen a different page size if I had known more about the common sizes across the various POD companies. The page size I chose at Lulu is not supported by CreateSpace, which is Amazon’s POD arm. When you publish through CreateSpace, you get distribution through Amazon.com, which isn’t the necessarily the case with other POD publishers. (I’ve read several blog posts about how some authors use the same sets of files to simultaneously publish books through multiple POD firms to maximize the distribution of their content.)
In these tight economic times, POD publishing makes a lot of sense, particularly when you want to release content in print but don’t want to invest a lot of money in printing multiple copies that you have no guarantee of selling. The POD model certainly was a good match for Technical Writing 101, so we decided to give it a try.
I’ll keep you updated on our experiences with POD publishing in this blog. If you have experience with POD, please leave a comment about how it’s worked for you.
Think global
We are joining with a couple of other technical communication companies to form the TechComm Alliance:
Three companies—Cherryleaf Ltd., HyperWrite, and Scriptorium Publishing—are forming TechComm Alliance to help us handle technical communication projects around the world. We are located in the United Kingdom, Australia, and the United States, respectively, and each company has customers in both its home location and in other countries. TechComm Alliance will make it easier to work with global companies that need services worldwide.
How will this work? We expect to:
- Work together on large projects that require support in multiple locations. For instance, Scriptorium might be implementing structured authoring for a U.S. company that also has operations in Europe and Australia. During rollout, instead of sending a Scriptorium consultant around the world, we partner with Cherryleaf for the training in Europe and with HyperWrite for the training in Australia. The result? Our customer saves on travel expenses, and our consultants spend less time in airplanes.
- Refer projects to each other. Each company has (and will continue to have) clients around the world. When we feel that a local presence would benefit the customer, we can refer the project to our alliance partners.
- Produce webinars and other events together. I’d like for Scriptorium customers to benefit from the expertise of our partners, and we are working on joint webinars.
TOC: Tim O’Reilly/Publishing 2.0
What do killer Internet applications have in common?
- Information businesses (publishers??)
- Software as a service
- Internet as platform
- Harnessing collective intelligence
Web 2.0: harness network effects to get better the more people use them.
- Google: every time someone makes a web link, they contribute
- eBay: critical mass of buyers and sellers hard for others to enter
- amazon: 10M user reviews
- craigslist: self-service classified ads, users do all the work
- YouTube: viral distribution, user creation, user curation
Each of these companies is building a database whose values grows in proportion to the number of participants — a network-effective-driven data lock-in. (gulp)
Law of conversation of attractive profits
- When attractive profits disappear at one stage the opportunity will usually emerge at an adjacent stage.
- PCs used to be expensive. Software became expensive. Free precursor to rediscovery of value in some other form.
And thus, if digital content is becoming cheap, what’s next? What’s adjacent?
For publishers, the question is: where is value migrating to?
Asymmetric competition
- craigslist has 18 employees, #7 site on the web (2005 numbers)
- All others in top 10 have thousands of employees.
Curating user-generated content
- The skill of writing is to create a context in which other people can think. — Edwin Schlossberg
- The skill of programming is to create a context in which other people can share.
Collaborative authoring
- Collaboration works best for modular structure
- instructables.com
What job does a book do? What is a book’s competition?
- Harry Potter’s competitor is World of Warcraft
- Encyclopedia Britannica — Wikipedia — Google
- Books compete with information available online
- Teaching/reference/edutainment
Search is most important benefit of content being online
“Piracy is progressive taxation”
- Benefits the books at the bottom that would be lost
- How to balance/manage a progressive taxation system
- Gain more sales on the bottom end
DRM: “Like taking cat to a vet” (hold them very carefully and loosely!)
More options = happier users
Friends in new places
We’re pleased to announce that we have joined XMetaL’s Partner Program as a Certified Service Provider.
We will not be reselling XMetaL software, but we will begin offering XMetaL classes this summer.
This is really a customer-driven decision — we have clients asking us to develop XML and DITA implementations with XMetaL as the core authoring tool.
Accessibility suddenly moves up the priority list
Most web designers are aware of Section 508 requirements, which in essence require web sites to be accessible to persons with disabilities. However, Section 508 applies only to companies that sell to the United States government. Provided you’re willing to give up the U.S. government as a potential customer, your web site could be completely inaccessible.
