Entries categorized as 'tools'
I’m learning about Author-it’s HTML templates today, and how to insert Google Analytics code (or any other code, really, such as adding an automatically updating variable for “Last modified by” with user or date information.)
But my task today was to insert Google Analytics code. (As a prerequisite note, we already have all our documentation available on an external site at docs.imis.com.)
First, I created a Gmail account for our department. Next, I created a Google account. Then, I went to the Google Analytics page and signed up for an account there, entering the name of our externally-accessible documentation site.
At the end of the sign up process, Google gives you javascript code that you want to place directly above the closing body tag </body>. Fortunately, the way that Author-it sets up the HTML templates, all of your Author-it topic data is inserted at a point where the <aitdata> tag appears in your HTML template.
The HTML templates are typically stored in C:\Program Files\AuthorIT V4\Data\Templates\Plain HTML, although other types of HTML templates such as DHTML and HTML Help templates are also available. These are the files I discovered that Google Analytics needed to be installed on.
- I edited the body_template.htm file and located the <aitdata> tag. I copied the code from the Google Analytics page and pasted it below the <aitdata> tag.
- I edited the html_frameset.htm file and added the Google Analytics code in the <head> area as instructed by the Google Analytics help, which, as a side note, has a set of completely question-based articles, as in, all headings are written as a question. Fascinating. The topic is “What should I know about using Analytics with Framed sites?“
Now, republish the HTML from your Author-it topics and your Google Analytics code is available on each page. After about 24 hours we started collecting data.
Let me know your experiences using Google Analytics to monitor your user assistance site traffic - what metrics are you seeking? Are there any conversion goals we should set up? One metric I am considering is trying to monitor how often the Word .doc files are downloaded. Does anyone have tips or tricks for us?
Update: I found this blog entry, Tracking document downloads in Google Analytics, and it contains hints at what I need to do to track our Word document downloads. However, I think that this article from the Google Analytics Help, How do I track files (PDF, AVI, or WMV) that are downloaded from my site? contains the method I’ll try first.
Categories: tools · work
Tagged: analytics, author-it, AuthorIT, Google Analytics, HTML, HTML Help, site statistics, technical communications, techpubs, tools, user assistance, web site analysis, web traffic, XHTML
I’ve been doing quite a few photo projects lately, but mostly with digital items. I did my family photo card this year with a Photoshop layout similar to the ones on purplestork.com, for example. The digital environment is fun, but I still enjoy the paper arts as well, scrapbooking, stamping, and card making, and I generally love altered ordinary items.
This post shows my first attempt at altering Altoid tins. I’m putting miniature scrapbooks inside of the Altoid tins for some friends and family members this year. Hopefully they’re not reading this blog post before they get their gift!
For me, the secrets are in getting the dimensions of the rectangles for the top, bottom, and insides of the tin. I say it’s 2.25″ by 3.5″ but you have an extra eighth of an inch to work with on the longer side.
I cut paper rectangles 2 1/8th inch by 3 1/2 inch, and then used a corner rounder I bought for $8 at Michael’s. A 3 7/8th inch long side also works if you want to cover more but you have to glue precisely.
For some of the tins, I cut a 1/2 inch by 12 inch strip of paper to cover the side, although you could use 11 inch paper length and still get all the way around the tin. Ribbon also works well, so I used that for some of the circumferences of the tins.
With my foam brush I put a thin layer of Mod Podge on the tin and put the paper rectangles on, then smoothed out any air bubbles. I didn’t need to do anything to the tin itself except for wash it out, no sanding required.
I bought the tins from an Austinite on Craiglist - over 30 tins for $3. I had all the supplies in my growing scrapbooking and stamping collection except for that corner rounder.
And if all those supplies are not around your house but you want to get your hands on some altered Altoid tins, pop over to Etsy.com. Those designs blow mine out of the water!
Categories: tools
Tagged: altoids, arts, craft, paper, photos, scrapbooking, tins
I’m learning more about ebooks thanks to some recent inquiries related to my work for One Laptop Per Child (OLPC) to collaborate on the kid’s user guide. I’ve been so busy with that I’ve barely had time to blog. I’m learning so much it’ll add to the blog entries later.
But I have been noodling on the fact that Amazon’s Kindle and the OLPC XO are at the exact same price - $400 - and that the XO can be used as an ebook reader (PDFs preferred.)
I’m going to try to do a comparison here, but please realize I’m no ebook reader expert nor have I owned one in the past. So I really have no business writing this at all other than my innate curiousity and love of researching and then presenting information.
On to the interesting comparison - let’s look at other parameters, and feel free to suggest your own. Like I say, I have no business writing an ebook comparison so do pitch in where you see fit.
Amazon’s Kindle ebook reader versus the One Laptop Per Child XO in ebook mode
| Comparison item |
Kindle |
XO |
| Dimensions |
 7.5″ x 5.3″ x 0.7″, weighs 10.3 ounces |
 9.5″ x 9.0″ x 1.25″, weighs about 3 pounds |
| Price |
$400, free shipping |
$400, about $25 shipping, $200 is a tax-deductible donation, so slight discount depending on your US tax bracket, I suppose |
| Content |
DRM content, can’t read PDFs unless you have a Windows PC and convert them first. |
Mostly PDF, but plans for more format support. With the built-in browser (Browse Activity), many reading materials are available such as Project Gutenberg. |
| Usability |
Robert Scoble has a harsh usability review of the Kindle. |
Robert Nagle I hope will review it in the future, but he has a great review of the possibilities as an ebook reader for kids. And I like the review written by a 12 year old. |
| Battery |
30 hours |
4-5 hours |
| Wireless connectivity |
Uses a wireless cellular network it calls Whispernet to deliver your Kindle content. It’s EVDO. |
Uses 802.11b and comes with a free one-year subscription to T-Mobile wireless service. |
| Screen |
monochrome: 600 x 800 pixels (167 dots per inch) |
monochrome: 1200 x 900 pixels (200 dots per inch), color: 1024×768 perceived (it’s complicated, see the hardware specs PDF.) |
| Warranty |
one year |
30 days |
Gizmodo already put the Kindle up against the Sony Reader in this online poll. I realize that the OLPC XO is intended to be a kids laptop, and it’s not really fair to pit it against the Kindle because that’s not the design of the device (nor the intentions of the project behind the device.) But your $400 might be well spent here.
By the way, I read about expected XO delivery information from the new XO User’s Facebook Group 50 members and growing. If you order now, you’ll get your laptop arund the same time as a child in Afghanistan, Cambodia, Haiti, Mongolia or Rwanda - in early 2008. See Shipping information on laptop.org.
Categories: tools
Tagged: computer, ebook, ereader, evince, kindle, laptop, notebook, OLPC, PDF, reader, XO
In trying to modify multiple Author-it topics (okay, 5,119 topics) with variable assignments, I have had to work with the XML output that Author-it exports.
To export to XML, you select a topic or multi-select topics, then right-click on the selection and choose XML > Save to file.
Turns out, Author-it outputs its XML encoded with UTF-16, but apparently most Windows applications understand UTF-8. When I tried to open my freshly export XML file, XML Copy Editor gave me an error.
So I had to discover how to convert the XML from UTF-16 encoding to UTF-8 (and you can’t just open it in Notepad on Windows and change the 16 to 8, there are other embedded characters indicating the encoding, and, well, it’s encoded.)
First, I used the identity transform documented many places, my favorite place being the XSLT Cookbook, to convert the Author-it output to UTF-8. Here’s the XSLT code for that:
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:output encoding="utf-8"/> <xsl:template match="@*|node()">
<xsl:copy> <xsl:apply-templates select="@*|node()"/>
</xsl:copy> </xsl:template>
</xsl:stylesheet>
I just ran the above transform against the AuthorIT Objects.xml file I exported, using the Instant Saxon XSLT processor.
Then, I wanted to remove all <VariableAssigments> elements, effectively removing an entire node. Again, the identity transform (or copy transform) was effective. And, I learned that I had to identify the AuthorIT namespace thanks to this excellent helper article, Handling Default Namespaces on topxml.com.
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
xmlns:ait ="http://www.authorit.com/xml/authorit">
<!--Match everything using identity copy-->
<xsl:template match="@*|node()">
<xsl:copy>
<xsl:apply-templates select="@*|node()"/>
</xsl:copy>
</xsl:template>
<!--Remove all the VariableAssignment nodes-->
<xsl:template match="ait:VariableAssignment">
<xsl:comment>Removed VariableAssignment element</xsl:comment>
</xsl:template>
</xsl:stylesheet>
This transform is pretty dangerous, though, because it’s taking away all the VariableAssignment elements, and you might have valuable metadata stored that you would quickly blow away. So use with care.
This workaround is likely also useful for DITA and XHTML files, because Author-it outputs its DITA and XHTML files as UTF-16. I haven’t investigated its usefulness for those areas, but a quick search on the Author-it-users group on Yahoo revealed that sometimes people want UTF-8 rather than UTF-16. So, I hope this helps.
Categories: tools
Tagged: author-it, AuthorIT, DITA, identity template, software, techpubs, tools, UTF, UTF-16, UTF-8, writing, XML, XSLT
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.
Categories: tools
Tagged: author-it, DITA, information architecture, OASIS, online help, PDF, technical writing, techpubs, troubleshooting, user assistance, Word, XHTML, XML
I’ve signed up for the Give 1 Get 1 program for One Laptop Per Child, and just received the email today, November 12, 2007, with the link to the site, www.laptopgiving.org.
I read the terms and conditions with interest because I am seriously considering purchasing a laptop either for my son, who is four, or for his classroom of four-year-olds. Plus, I’ve been volunteering to help with their end-user documentation.
I’d love to buy one for every classroom at my son’s preschool but that’ll take some fundraising. I’ll boldly propose here that you can contact me if you’re interested in buying enough for a small preschool in Austin, Texas in addition to kids in least developed countries around the world.
I absolutely LOVE the spirit of the support statement. It reads as follows:
Neither OLPC Foundation nor One Laptop per Child, Inc. has service facilities, a help desk or maintenance personnel in the United States or Canada. Although we believe you will love your XO laptop, you should understand that it is not a commercially available product and, if you want help using it, you will have to seek it from friends, family, and bloggers. One goal of the G1G1 initiative is to create an informal network of XO laptop users in the developed world, who will provide feedback about the utility of the XO laptop as an educational tool for children, participate in the worldwide effort to create open-source educational applications for the XO laptop, and serve as a resource for those in the developing world who seek to optimize the value of the XO laptop as an educational tool. A fee based tech support service will be available to all who desire it. We urge participants in the G1G1 initiative to think of themselves as members of an international educational movement rather than as “customers.”
I’ve been working on documentation for the XO laptop in the wiki at wiki.laptop.org/go/Simplified_user_guide and then taking the wiki content over to an Author-it instance. I’ll write more later about a wiki-based workflow, especially with translation in mind, and we are putting a process in place. Please, feel free to edit that page or contact me if you are interested in contributing.
Personally, the most difficult part so far has been my limited ability with design and layout. I have grand visions but feel my layout skills are inadequate for a kid- and parent-friendly look within Word. Nonetheless, it is an exciting time to be a small part of such an influential project.
I’m one of the friends, family, and bloggers who is willing to help with the XO laptop. So I urge you to go to www.laptopgiving.org and put your U$399 to good use.
Categories: tools · wiki · writing
Tagged: content, customer created content, customer feedback, customer support, education, G1G1, laptop.org, OLPC, rss, social media, wiki, writing, XO, XO laptop
November 8, 2007 · 1 Comment
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.
Categories: social media · tools · writing
Tagged: findability, information architecture, OLPC, probability, research, search, webaroo, wiki
More note taking at sessions at the Quadralay WebWorks Publisher RoundUp. This session is with Stephanie Cottrell Bryant, author of Videoblogging for Dummies. She’s an ePublisher user who embeds video demonstrations of software within online help.
Customers love video embedded in the online help. Time saving for them, and no need to attend a training class. Her customers love it, love it, love it.
Tool kit she uses - Camtasia studio, Framemaker, and WebWorks ePublisher.
Need a script - but you might already have it, like a list of steps in a task.
Annoyance - don’t take your whole desktop while capturing screencasts. “Your desktop icons are like seeing your underwear on a clothesline.” 
Also, don’t show the time of the day (like 4:00 AM) that you captured the screens, it’s sort of too much information.
Sizing of about 320 by 240 is about the right size for YouTube. Or 480×360 if you need something slight larger. If you’re delivering the video on a hard drive (installed as part of your product), you can make it even bigger. But for Internet or CHM deployment, keep it small.
Record audio first, then replay the audio while you record the video - the timing will be easier to get synched up.
She likes to use a “highlight click” feature that shows a subtle red circle showing where you click on the screen. She also modifies the cursor so that it’s larger and a yellow color while capturing the screencast.
She “cropped” out the first part of the video where she moved the screen around to the optimal location.
She recommends Flash for video output (.swf file). But if you know people are using Windows, you can make Windows Media files. If you know they’ll only be played back on an iPod, make a QuickTime file. If you want to send these video files to someone else and they don’t have Camtasia, save them as AVI - they’ll be larger files but the recipient will be able to compress them as needed and make another format. Also, any video editing software can edit AVI files.
If you want to use embedded video within an HTML file, don’t use Flash, however.
Goes into Frame, creates relative path to the movies (which is in Files folder within the ePublisher directory system), then generates the HTML using ePublisher.
She uploaded javascript to the WebWorks wiki that writes the embedded video code in on the fly, so that Internet Explorer doesn’t put a popup in front of the user, complaining about the embedded object.
In the javascript call to the video file, she’s adding an extra 10-20 pixels to the height dimension so that the player bar shows up at the bottom.
She uses conditional text in FrameMaker called “Passthrough” for all her javascript code so she can put it right into her FrameMaker file.
Categories: techpubs · tools
Tagged: embeded video, ePublisher, online help, popup, screencast, video, WebWorks
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?
Categories: DITA · tools · wiki
Tagged: conversion, CoScriptor, ePublisher, Framemaker, Quadralay, WebWorks, wiki, wikitext, Word
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.
Categories: tools
Tagged: author-it, AuthorIT, CMS, content management systems, DITA, HTML, HTML Help, Java Help, Microsoft Windows Help (RTF-based), Oracle Help, PDF, publishing, robohelp, software, technical communications, technical writing, techpubs, tools, webinar, Word, XHTML, XML
Anne is a senior technical writer at Advanced Solutions International. Read 
