Wednesday, March 10, 2010

Flare training in Toronto 

MadCap Software will be offering two one-day training sessions on MadCap Flare in Toronto.

The first course, on April 23, is Advanced CSS (PDF link) taught by Neil Perlin (who is also doing a one-day session on topic-based authoring as part of the STC Toronto education day).

The second course, on May 14, is Advanced Single Sourcing, taught by Mike Hamilton.

Both courses are $599. The location, at Elections Ontario, on Rolark Drive in Scarborough, is a bit awkward (Birchmount and Ellesmere), so I may have to pass on these. In looking at the outlines, I think the CSS course would probably be more useful. The single-sourcing course looks like it covers a bit too much material for one day.

For more information, or to register, contact Jennifer Morse.

Labels: ,


// posted by Keith, on (permanent link): 6:38 AM (0) comments

Tuesday, March 09, 2010

What can we learn from history 

Here's an interesting summary of and commentary on an article by Saul Carliner, “Computers and Technical Communication in the 21st Century”. Having taken a course from Carliner, I can vouch for his knowledge of the field and his presentation skills - I'm sure the article is both well researched and entertaining. It's part of a technical communication textbook, which I just might track down.

I appreciate Carliner’s grasp which admirably summarizes and structures decades of volatile developments in IT. I was surprised to learn that several technologies that I had taken for granted had been introduced shortly before I started in TC.

It’s interesting to see that some early practices still stick around, for better or worse: We’re still debating whether technical or language skills are more valuable. Carliner’s history is one of evolution, not of discrete stages where a new stage replaces the previous one. So the old is not necessarily bad, the new is not better just because it’s new (and Carliner doesn’t claim it is).

Labels:


// posted by Keith, on (permanent link): 6:03 AM (1) comments

Wednesday, March 03, 2010

Flare 6 released 

MadCap Software announced the release of Flare 6 today. I found out about it on Tom Johnson's blog about three hours before the e-mail from MadCap arrived in my inbox at work.

So of course I downloaded it and installed it as fast as I could manage. On first glance, it doesn't look that different from Flare 5, though it's obvious they've been making some subtle but welcome usability tweaks in the interface. But there are some interesting new features. One I will definitely be using is the tagging feature that lets you add metadata to files. There's also a new output format for mobile devices.

Along with Flare, MadCap also released new versions of Analyser, XEdit, and Echo.

Tom's blog post includes a podcast interview with MadCap's Mike Hamilton, who talks about the new features and drops a few tantalizing hints about future development.

Labels: , ,


// posted by Keith, on (permanent link): 6:21 AM (0) comments

Tuesday, February 23, 2010

WritersUA blog 

The WritersUA conference is being held next month in Seattle. I won't be going, so I'll be following the WritersUA blog and monitoring the Twitter feed (#WritersUA). My colleague, Scott Nesbitt, will be attending and presenting, so I'm sure I'll get first-hand reports from him when he returns.

Labels:


// posted by Keith, on (permanent link): 11:44 AM (0) comments

Mallard - yet another doc markup system 

Mallard is another topic-oriented markup language designed to provide online help. It's currently being used as part of Gnome. There are some superficial similarities with DITA, and there's been a bit of discussion about this on the DITA mailing list, with people wondering why they didn't just use DITA in the first place. If you're at the WritersUA conference next month, you'll be able to see a demo from the developers.

Labels: ,


// posted by Keith, on (permanent link): 6:06 AM (0) comments

Monday, February 22, 2010

Artificial retinas making progress 

Scientists continue to make progress in restoring vision by means of an artificial retina. According to this article, implants are now up to 60 pixels and the next step will be 200. That's still far, far below the resolution of the human eye and visual system, but it is enough to help people navigate their surroundings.

The first-generation implants were successfully tested on six patients, but only held 16 electrodes (4-by-4-pixel array), which enabled the crude perception of lighted areas versus darkness after about 15 seconds. The second-generation implant upped the electrode array to 60 electrodes, which enabled 34 test patients to recognize doorways and windows as well as the edges that assist in navigation, such as walls and low-lying branches, after about 3 seconds.

The goal of the third generation of the implant will be to increase the electrode array to more than 200 electrodes, which will enable the near instantaneous recognition of text for reading, pictures and all the edge cues needed to navigate the world unaided. Ultimately, the artificial retinal will contain over 1,000 electrodes, which should restore instantaneous recognition of faces and other fine details that should fully integrate patients back into everyday society.

Labels: ,


// posted by Keith, on (permanent link): 6:36 AM (0) comments

Wednesday, February 10, 2010

Cures for information exclusion 

If you've been working as a technical writer for any length of time, you'll be familiar with the concept of information exclusion, even if you don't call it by that name. It happens when you aren't included in the project development loop, or developers update software without telling you, or that a project release is due in a week, and hey - we need the help updated too.

Tom Johnson has a good article about it, and what you can do to fight back. It means digging into your organization's bug tracking system.
Don’t be intimidated by JIRA, or whatever bug tracking software you use. JIRA is your best friend, because now that you know the secret — that JIRA controls all information about a project — you can start to leverage this information source to influence updates and changes to the application as you see fit.

You know that capitalization error on the home page of your app that is driving you nuts? Stop complaining about it in project meetings. Just log it in JIRA and it will probably get done. How about the error message box that says, “Object reference not set to an instance of an object.” You’ve been telling developers for months that no one will understand it. But they aren’t waiting for an email from you to specify how to fix it. No, they’re waiting for the item to appear in JIRA. Like a cook waiting for an order, developers will simply see the request on their screen and get to work.

Not every thing you slip into JIRA will get implemented. The tough fixes will be procrastinated, just like you have procrastinated the toughest help topics in your help. When developers feel weary and tired, and when they’re winded from playing too much ping pong, they’ll cherrypick the easy JIRA items that require nothing but simple text updates — your capitalization pet peeves, the label misspellings, those inane on-screen messages that developers typed while they were half-asleep. As long as you stick your requests in JIRA, they will eventually get done.

I should note that this won't work in every organization. Not all control their development process through a bug tracking system and some use separate bug tracking and change management systems to manage bugs and enhancements. But in general, getting access to the tools that your developers and QA group use to track their work is a good idea.

Labels: ,


// posted by Keith, on (permanent link): 6:16 AM (0) comments

Tuesday, February 09, 2010

Web publishing and hyperfiction 

As new media and technologies develop, writers are taking advantage of the possibilities of hypertext and rich media to create new forms of online documentation. But most fiction, even if published online, remains firmly in the linear mode. I've thought for years that hypertext was the ideal medium for some types of fiction - in particular, the big sprawling, multiple point of view novel (Stephen's King's Under the Dome, Larry Niven and Jerry Pournelle's Lucifer's Hammer). I mention SF novels specifically, because I thought that SF writers would be the first to exploit these new media possibilities, but this hasn't been the case, at least until recently.

In a guest post on Charlie Stross' blig, Elizabeth Bear writes about an exciting project called Shadow Unit. " The FBI's Behavioral Analysis Unit hunts humanity's nightmares. But there are nightmares humanity doesn't dream are real. The Behavioral Analysis Unit sends those cases down the hall. Welcome to Shadow Unit."

It's written as hyperfiction, but more than just a linked series of stories, with a blog, a wiki, and message boards, so fans and readers can contribute. In her post, Bear uses her experience with Shadow Unit to offer up some guidelines for how to make such a project succeed, both on a literary basis and financially. Technical writers should take note - these are exactly the sort of problems that many of us are facing in expanding our published content beyond books and PDF manuals, and working with a community of users to incorporate user-developed content.

t's easy as heck to lose people in the corners. Hyperfiction by its nature is sprawling--it rewards curiosity, investigation, peering into corners. (Reading dozens of blog comment threads for scraps of narrative, for example, is much easier at the beginning of a five-year narrative run than the end.)

It will help, in the future, to develop protocols for mapping hyperfictions (a sort of table of contents, perhaps, graphically represented in the form of a web? Shadow Unit has done this with a "suggested reading order" page on the wiki, but experience has revealed this to be helpful but not entirely adequate.).

On the other hand, some of the fun is the discovery, and the fan community delights in sharing their discoveries with each other, so we intentionally hide stuff in inobvious places. There's a balance to be struck between the fans who adore logic puzzles and the ones who just want to read a damned story, and accommodation must be made for both.

We do this with a BBS where (a) can show off their finds to (b).

Labels: ,


// posted by Keith, on (permanent link): 6:39 AM (0) comments

Saturday, January 30, 2010

Running MadCap Flare on a Mac 

Although MadCap Flare is a Windows only tool, it is possible to run it on other platforms by using virtualization tools, as this post from The Tech Pub points out.

With virtualization, I had a few choices. Mac has a program called Parallels, which allows you to run another operating system (Windows, for example) on top of the Mac operating system, for around 80 bucks.

There’s an Open Source solution, VirtualBox, offered by Sun, that will also run on Mac (or Windows, Linux, or OpenSolaris).

And also, there is VMware’s Fusion for Mac, which, like Parallels, for around 80 bucks will let you run your second operating system on top of Mac OS X.

In the end, the choice ended up being made for me – my company bought licenses for Fusion (since we develop software that runs on VMware, it was the logical choice).

Once installed, I used Fusion to load a pre-built Windows XP virtual machine. Once booted, the virtual version of Windows is no different than Windows running on a dedicated device – I was able to install Flare, adjust my environment settings, and I was ready to go. The real beauty, of using Fusion, though, is Unity mode. This allows you to run your Windows applications as if they’re running natively, on Mac. Basically, Unity mode strips away the Windows OS front-end and allows the Windows apps to be launched directly from Mac OS X. They appear right in the dock when running, just like any other Mac application.

Labels: ,


// posted by Keith, on (permanent link): 3:01 PM (0) comments

Thursday, January 21, 2010

DITA Open Toolkit GUI review 

If you've tried learning DITA by using the DITA Open Toolkit, you've probably figured you're doing things the hard way, and you are - unless you like running complex ANT scripts from the command line. There are tools to make using the Toolkit easier. Tony Self's WinANT has been out for a while. Now there's another front-end to the DITA Open Toolkit - this one simply called the DITA Open Toolkit GUI. It's written in Java and is open source.

I haven't been doing anything with DITA recently, but Leigh White has and posted a review of it on the DITA users Yahoo Group. Here it is, reposted with permission.

I just spent some time playing with this tool and find it a clean, quick alternative to the more complex Echidna/WinANT tool. DITAOT-GUI provides a simple interface, allowing users to select a map, DITAVAL filter, output location and output type. It bypasses the need to create a build file but therefore does not allow the use of parameters and properties to specify additional aspects of the build. Echidna/WinANT, on the other hand, does offer an interface to many of these parameters and properties and can create the corresponding build file on the fly. If you don't need the additional specifications offered by Echidna/WinANT, then DITAOT-GUI is an excellent, streamlined tool. I admit I did not find the Ditamap Composer to be very intuitive, but I didn't spend a lot of time with it.

There are several low-cost or free tools for ditamap creation, but very few for interfacing the OT. The real value of DITAOT-GUI seems to be more in its interface to the OT rather than as a map creation tool.

Labels: ,


// posted by Keith, on (permanent link): 6:05 AM (0) comments

Monday, January 18, 2010

It's official - technical writing is a good career 

According to the Wall Street Journal, technical writers have the 13th best job in the U.S., ranking behind actuaries and dental hygenists, but ahead of web developers. You can read about the scoring criteria here. Factors considered included the job's physical and emotional environment, income, hiring outlook, physical demands, and str

I'm a bit surprised that the rating was that high, given what I've seen happening in the field over the last couple of years. But I guess it's relative - compared to auto workers, we're way ahead of the game.

Labels:


// posted by Keith, on (permanent link): 6:08 AM (0) comments

Saturday, January 16, 2010

Some techical writing humour 

You don't see a lot of jokes about technical writers (I guess we're just not as funny as lawyers or banjo players), so it's nice to see some cartoons from Ben Minson, who is both a technical writer and cartoonist.

Labels: ,


// posted by Keith, on (permanent link): 1:59 PM (0) comments

Thursday, January 14, 2010

Using DITA for narrative docs 

Although DITA was originally designed for technical documentation, it's generic enough that it can be used for many other types of documents. This article by XML expert, Elliot Kimber, explains how.
This is the first in what will be an occasional series of DITA application discussions around the subject of applying the DITA standard to Publishing business problems (that is, using DITA-based XML markup as the source for documents produced by Publishers, as opposed to documents produced by product companies). Because DITA comes out of the technical documentation domain (it was developed by IBM as their next generation XML application for technical documentation, especially documentation delivered on the Web or as online help), most of the practical information about DITA reflects technical documentation applications.

But DITA is equally applicable to many Publishing applications, including traditional narrative documents that don't seem, at first look, like candidates for ditification.

Labels: ,


// posted by Keith, on (permanent link): 6:49 AM (0) comments

Monday, January 11, 2010

10 trends in technical communication for 2010 

Here's another list of trends in technical communication for 2010 - this one from Cherryleaf. This list is a little more extensive than the one I posted recently from Scriptorium, but scovers many of the same areas. Here's a couple:
4. The rise of User Generated Content and the networked manual

By networked content, we mean integrating content that resides on other web sites. The Semantic Web and other Web technologies will allow us to draw in relevant content from elsewhere. So perhaps we’ll see the emergence of collections of open source content (”content assets” or “process assets”) that technical authors can draw upon when they are writing.
5. More collaborative and conversational authoring

We’ve talked a lot this year about integrating original content and commentaries on content from both in-house Subject Matter Experts and end users. See our previous posts on user generated content.

Labels:


// posted by Keith, on (permanent link): 6:41 AM (0) comments

Wednesday, January 06, 2010

2010 trends in technical communication 

Scriptorium Publishing have published a list of the trends they see affecting the the technical communication industry this year. It's a short article but from what I've seen in my own job, it's pretty much dead on the mark.
Desktop authoring begins to fade

Everyone else is talking about the cloud, but what about tech comm? Many content creation efforts will shift into the cloud and away from desktop applications and their monstrous footprints (I’m looking at you, Adobe). When your content lives in the cloud, you can edit from anywhere and be much less dependent on a specific computer loaded with specific applications.

I expect to see much more content creation migrate into web applications, such as wiki software and blogging software. I do not, at this point, see much potential for the various “online word processors,” such as Buzzword or Zoho Writer, for tech comm. Creating documents longer than four or five pages in these environments is painful.

In the ideal universe, I’d like to see more support for DITA and/or XML in these tools, but I’m not holding my breath for this in 2010.

Labels:


// posted by Keith, on (permanent link): 6:44 AM (0) comments

Tuesday, December 29, 2009

If no one reads the manual, that's OK 

Poor Tom Johnson. Instead of being at home enjoying time with his family between Christmas and New Years, he's at work finishing off a manual that probably no one will ever read. Which sends him off on a long and interesting post about manuals and whether anyone really reads them. Its something that writers think about, in those dark hours at 3 a.m. when sleep refuses to come and their minds are filled with visions of dusty, unopened binders, the product of their toil gathering dust on shelves. But as Tom points out, maybe there are good aspects to this.
Not many writers consider the positive aspects of users not reading the manual. If you do a lousy job on the manual, or if some SME discovers typos and inaccuracies, you can just laugh it off by saying no one really reads the manual anyway.

But consider the opposite scenario where everyone reads the manual. Is this a scenario you want? No. Because if everyone has to read the manual to figure out the product, it means the product is so unintuitive and user hostile it’s probably going to tank on the market and you’ll soon be out of a job anyway.

Also, if so many people are consulting the help, you probably aren’t contributing enough on the design/usability side of your technical writing role. Remember that you’re part of a team building a solution to a problem. You want the user interface to be simple and intuitive enough to not require a manual. So if only 10 percent have to consult the manual to figure out the product, that’s a good thing.


Update: Here's a somewhat different perspective from Patty Blount.

Labels:


// posted by Keith, on (permanent link): 7:29 AM (0) comments

Monday, December 21, 2009

DITA Open Toolkit 1.5 now available 

After a lengthy beta process, DITA Open Toolkit version 1.5 is now available. From Robert Anderson's post on the DITA mailing list:
It is with great pleasure that I'm announcing the final build of the DITA
Open Toolkit version 1.5, now available to download from SourceForge! This
package has been a long time coming, and includes far more enhancements
than can be listed here; a few notable and recent enhancements include:
* Full support for the latest version of the DITA 1.2 specification;
* Many new enhancements, parameters, and fixes for PDF processing,
including the ability to override PDF with a plug-in;
* TocJS plug-in now shipped in the standard and full packages;
* Improved support for non-English character sets in RTF, and for mixing
languages in PDF;
* A sample Ant build script
(samples/ant_sample/sample_xhtml_plus_css.xml),
along with a small CSS file, used to demonstrate how to drastically change
the look-and-feel of XHTML output with a small CSS override.

There's a link to the download packages here.

Labels: ,


// posted by Keith, on (permanent link): 11:54 AM (0) comments

Wednesday, December 16, 2009

Periodic Table for Visualization Methods 

If you need help trying to figure out a way to graphically display some information, the Periodic Table for Visualization Methods is worth a look. It's set up like the standard periodic table of elements, but each cell is a different type of graphic. When you mouse over the cell, a popup window displays an example along with a brief explanation. Graphics are grouped by type of visualization: data, strategy, information, metaphor, concept, and compound.

It's a handy tool, although I do wish you could display the example graphics in a separate, larger browser tab.

Labels: ,


// posted by Keith, on (permanent link): 6:36 AM (0) comments

Monday, December 14, 2009

Content management ROI calculator 

The Rockley Group have updated their Content Management System Return on Investment calculator. If you're considering implementing a CMS, this is definitely something you should look at.
We first created the CMS ROI Calculator as a companion piece to our book Managing Enterprise Content: A Unified Content Strategy. We’ve recently revamped it to reflect current industry costs and we’ve added a new section on publishing tool costs.

If you are interested in purchasing content management technology, this calculator will assist you in determining costs.

Note that developing a successful business case is about a lot more than running numbers. You need to:

* Analyze your situation
* Determine your pain points
* Identify what those pain points are costing you
* Identify what those pain points are costing you

And of course you need to put these numbers into the context of a business case that will help your organization to understand the benefits of moving towards content managemen

Labels: ,


// posted by Keith, on (permanent link): 6:08 AM (0) comments

Monday, December 07, 2009

Taking control of Word 

The first thing I do when I'm working with a new installation of Word is to go into the Options dialog and customize all the settings. Generally, that means turning off most of the automated editing features that Word likes to add. CyberText Newsletter points out a good TechRepublic article that details how to turn off many of Word's annoying "features".
One of the most common complaints about Microsoft Word is its insistence on taking control of the wheel. Many users get completely blindsided by some of Word’s automatic changes, and even the more experienced among them often just live with Word’s shenanigans because because they don’t know how to disable them.

If you’ve gotten more than your share of support calls from users trying to wrestle Word into submission (or pulled out your own hair on a few occasions), the list below will help you quickly cut Word down to size.

Labels: ,


// posted by Keith, on (permanent link): 6:05 AM (0) comments

Friday, November 27, 2009

Technical communication in the kitchen 

Tom Johnson has an interesting post about technical communication that was inspired by his role in helping to prepare the Thanksgiving dinner. It's a good article that points out quite clearly how documentation has to fit the needs of the audience.
The recipe calls for 4 bananas. After I added 3, Jane said to stop because there wouldn’t be any more room in the pie. But perhaps the pie’s final shape was meant to be convex, rounded at the top like a small hill? And if I put the bananas at the bottom and the pudding on top, wouldn’t that be uneven? Wouldn’t it be better to mix the two somehow for a more even distribution?

Finally, the banana cream pie recipe made no mention about whipped cream. Am I supposed to whip cream and add it to the top of the pie, like I’m accustomed to seeing in coconut-cream pie? Or is the custard filling the cream component of the pie?

I repeated several times my desire for a “man’s cookbook,” one that would provide more details, more straightforward explanations, and more hand-holding.

Yet for Jane, she preferred the abbreviated, concise recipe style because she’s familiar with the terminology and methods. When a recipe says to prick a pie shell, she knows about how many pricks to make, how deep to make them, and how much space between all the pricks. When I see instructions to prick a pie shell, I’m thinking up all kinds of scenarios about what this could mean.

Labels:


// posted by Keith, on (permanent link): 6:42 AM (0) comments

Tuesday, November 24, 2009

Using a wiki for technical communication 

Sarah Maddox has published an article about using wikis in technical communication, based on her experience as a writer with Atlassian, the developers of the Confluence wiki. As a bonus, when you download the PDF you get another article about trends in British technical communication.

Labels: ,


// posted by Keith, on (permanent link): 11:30 AM (0) comments

Wednesday, November 11, 2009

PowerPoint frustrates student 

I'm not a fan of PowerPoint. I've sat through too many deadly dull presentations by people who didn't know how to make a presentation interesting. So it saddens me to find out that universities have been infected by the PowerPoint virus. At least the students will be prepared for the real world when they graduate.
Professors who use PowerPoint tend to present topics very quickly when they don’t have to do anything but talk. If every example and every diagram is on the screen, there isn’t much time for me to take notes on the subject of each slide. Lectures aided by chalkboard visuals are easier to take notes from because I can write what the professor writes on the board at the same time. Also, because there is usually more chalkboard space than screen space, if I am behind on note-taking, the visual will probably still be on the board for me to copy a few minutes later. A lot of professors try to solve this problem by handing out the lecture slides before class, or by posting them online. While this is great for a lot of students, it doesn’t work for me because I learn best and am most engaged if I have to take notes as if my grade depended on having a great record of the class and I would never see the material again. In classes with handouts, I tend to zone out and have to work harder to pay attention. Studies have shown[pdf] that taking high-quality notes improves organic memory: I rarely use my notes after the lecture because the act of physically writing information down helps me remember more of what goes on in class.

Labels: , ,


// posted by Keith, on (permanent link): 7:06 PM (0) comments

Friday, November 06, 2009

Video of new Microsoft Help system 

Here's a video of a Microsoft program manager explaining the new help system in Visual Studio 2010.

Labels: ,


// posted by Keith, on (permanent link): 11:48 AM (0) comments

Wednesday, November 04, 2009

Tech writing and the Free Software Open Source Symposium 

Last Friday, my colleague, Scott Nesbitt attended the Free Software Open Source Symposium at Seneca College. There were three presentations on technical writing and open source, one of them given by Scott. He's written a post about his experience at the symposium, including summaries of the other writing-related presentations. It sounds like it was an interesting day, and hopefully the presentations will help raise the awareness of the importance of good documentation in the open source community.

Labels:


// posted by Keith, on (permanent link): 11:36 AM (0) comments

Friday, October 30, 2009

Lessons learned from using a wiki for documentation 

The always insightful Tom Johnson has been using a wiki to document a project, and he's written about some of the lessons learned. His experience parallels mine at work. If you're using a wiki, or planning to, read this article.
You have to think carefully about the navigation

The best-practice paradigm of topic-based authoring — authoring content in small chunks that you can manipulate and single source — doesn’t seem to apply to wikis. If you chunk each section as its own page, readers will bounce from page to page to page. It will become a dizzying experience of clicking and clicking.

Perhaps there’s a way to pull in sections from other pages, but I don’t know how to do that yet. Maybe wikis break down when it comes to single sourcing for multiple roles or audiences. Not sure here.

Depending on the wiki you are using and the web server it runs on, you may be able to include text from other pages in a wiki page - we use PHP include statements to do this - it works similar to the way text insets for in FrameMaker.

Labels: ,


// posted by Keith, on (permanent link): 6:44 AM (0) comments

Monday, October 26, 2009

Embedded user assistance 

Embedded user assistance or embedded help is the technique of building your help right into the application. It's probably the best way of handling help, but it's not often done because it requires extra effort on the part of both the writer and developers. TC World has a good article about how embedded help can improve usability in your applications.
Why is embedded help an excellent way to increase the usability of your software application?

Because embedded user assistance is task-specific, context-specific, and does not require users to search for it or ask the right question to find the answer. Unlike traditional online help, users continue their workflow and do not have to split their focus between two different windows. Best of all, users don’t see embedded help as help.

According to Wilbert Galitz in The Essential Guide to User Interface Design, a typical user interaction with documentation involves three steps: “(Users) need to find it, understand it, and apply that understanding to solve the task at hand.”

Online help is passive, with the user taking the initiative. Embedded help is non-intrusive and does not require the user to take the initiative, says Lynne Hall in the International Encyclopedia of Ergonomics and Human Factors.

Embedded help also encourages learning. According to Mike Hughes in the Cutter IT Journal, “users shift from a learning/exploration mode to a task execution mode … they stop exploring and experimenting.” Embedded help can delay that shift.

Labels: ,


// posted by Keith, on (permanent link): 6:09 AM (0) comments

Tuesday, October 20, 2009

How Google Wave can drown tech writers 

Google Wave has been causing a lot of buzz in the blogosphere recently. I'm not particularly interested, at least not right now - I have enough time keeping up with Twitter and Facebook. I can see the usefulness of it, but until it gets more widely adopted, I'm staying away.

However, it bears watching, as it and the media trends it represent are affecting the way that technical writers work. And if you don't keep up with the trends, or worse aren't even aware of them, you're likely to find yourself unemployed. will Kelly looks at the issue in more detail in this post.
The impending launch of Google Wave is something for every technical writer to watch. Because if they have been doing their job the same way from day one, then Google Wave's undertow is going to pull them down into the surf.

However, if they are embracing online collaborations tools, instant messaging, and related technologies then they are going to think Google Wave is game changer for technical communications because it offers a new range of communications and collaborations options.

An organization's adoption of Google Wave offers up a number of benefits for technical writers and their documentation. However, all parties involved in technical documentation development need to embrace Google Wave's new communications and collaborative model because Google Wave puts many long time staid processes online.

Labels: ,


// posted by Keith, on (permanent link): 6:14 AM (0) comments

Sunday, October 18, 2009

Install old-school help viewer in Windows 7 

If you're using, or planning on moving to, Windows 7, you'll find that the older version of Windows Help doesn't work. In other words, you won't be able to read .hlp files. However, if you need it, you can download and install the Windows Help viewer for Windows 7.

Labels: ,


// posted by Keith, on (permanent link): 10:38 AM (0) comments

Friday, October 16, 2009

Glossary specialization for DITA 1.2 

DITA 1.2, whenever it is officially finished, will have some major additions that will help authors work with glossaries. The DITA Adoption Committee has published a white paper that describes the glossary terminology specialization.

Labels: ,


// posted by Keith, on (permanent link): 6:20 AM (0) comments

Thursday, October 15, 2009

Technical writing a good career choice 

According to CNN, technical writing ranks in the top 50 career choices, based on pay and growth prospects, ranking 28 out of 50. The ten year growth rate in the field is rated as 20 percent, which sadly won't make up for the job cuts we've experienced in the last decade.

Labels:


// posted by Keith, on (permanent link): 6:02 AM (0) comments

Wednesday, October 14, 2009

Clean Up Text utilty 

Although most people can use Microsoft Word to get a document to look the way they want, few can do it efficiently. This can cause problems if you have to work with someone else's document -- for example, to import it into RoboHelp. Clean Up Text is a little Word Add-In that you can use to clean up documents that you receive from other people. It will perform several tasks, like removing leading andf trailing spaces and converting hard paragraph breaks to paragraph formatting.

Labels: , ,


// posted by Keith, on (permanent link): 6:41 AM (0) comments

Wednesday, October 07, 2009

STC drops print magazines, finally 

The STC (Society for Technical Communication) has finally done what many people have been suggesting for years, and announced that it will stop print distribution of its magazine, Intercom, and academic journal, Technical Communication. As of January 2010, they'll be online only (although print-on-demand copies will be available, at a price to be announced - and likely exorbitant).

Frankly, it's about time, especially for Intercom, which has seen its content outpaced by growing number of blogs and web sites related to our field. As for Technical Communication, I hardly ever read it, but I suppose libraries that want a printed copy can order one if they want.

Labels:


// posted by Keith, on (permanent link): 7:32 PM (0) comments

Tuesday, October 06, 2009

More articles about CSS 

Here's a selection of 15 articles about CSS (Cascading Style Sheets) compiled by Chris Spooner. They cover topics like the DIV tag, sprites, menus, and lists, and will give you a pretty good background in what CSS can do.

Labels: ,


// posted by Keith, on (permanent link): 11:30 AM (0) comments

Monday, October 05, 2009

Using WebWorks ePublisher to publish to Confluence wiki 

Recently Quadralay added support for the Confluence Wiki to its WebWorks ePublisher product, making Confluence the third wiki to be supported by ePublisher. This means that you can take large, complex documents and convert them to wiki format and easily publish them to the Confluence wiki.

The process of publishing to a wiki in ePublisher is a bit more complex than building online help, but still a lot easier than doing it manually. It's described in detail in this article from the ffeathers blog. If you use Confluence (or one of the other wiki formats that ePublisher supports - Moin Moin or MediaWiki) this article is worth a look.

Labels: ,


// posted by Keith, on (permanent link): 11:50 AM (0) comments

Using Google Docs to produce surveys 

Google keeps adding new features to Google Docs, for example, the ability to create forms. As CyberText Newsletter points out, you can use the forms tool to create simple surveys.

Labels: ,


// posted by Keith, on (permanent link): 6:02 AM (0) comments

Friday, October 02, 2009

A modern design for a newspaper 

Here's an interesting story about redesigning a newspaper using modern, web-based design principles. The designers didn't get the commission, but they did come up with some interesting ideas that sound quite workable, to me anyway.
Basic rule: Ignore all rules of newspaper design to start with and keep only the ones that are useful to the reader:

1. Optimize text for reading: Big leading, big body text. We did several reading tests and found this combination to work best for reading. We perfectly knew that this leading doesn’t look very newspaper like (see Basic Rule).
2. Reduction to two fonts: Frutiger Next and the new, amazing Frutiger Serif, a heavenly fit, honoring the great Adrian Frutiger for his life work.
3. Scannability and print link: Make the articles scannable by using key words in blue. If you speak German you can actually read the front page in 20 seconds by flying over the blue key words. It gets better: If you type any of those key words on the website search, you will get a list of articles with the respective keyword in a chronological order. That way you avoid the necessity to print http;//www.abc.com/abc style links in print. Links in print obviously doesn’t mean that you can click it, it means linking the paper to the online edition.
4. Order: Every page is structured from top left to bottom right. Important articles are top left, unimportant ones are bottom right.
5. Four columns for soft news, five columns for hard news, mixed 4/5 columns for sports. Ragged text for opinion.
6. Big pictures, big info graphics, use the strength of the paper medium

Labels: ,


// posted by Keith, on (permanent link): 6:00 AM (0) comments

Thursday, October 01, 2009

Conversation's dirty little secrets 

There's been a lot of buzz in the technical communication blogosphere recently about "community" and "conversation", a lot of it inspired by the release of Anne Gentle's excellent book, Conversation and Community. But conversation has two (or more) sides, and sometimes it's not all positive, as this post from Cherryleaf points out.
However…

However, earlier this week, I met up with a Documentation Manager of an Open Source application, already working in such an environment, who was facing some significant problems:

* Users were struggling to find information they wanted.
* The wiki-based user community platform was incomplete, out-of-date and incorrect in places.
* The content was the most viewed content of all the literature her company produced, but no-one wanted to take responsibility to manage the content.
* The Documentation team did not “own” the community content, but whenever there was an issue, they were asked to fix it.

The post goes on to list more possible problems and offers some concrete suggestions for addressing them. It's definitely worth a read.

Labels:


// posted by Keith, on (permanent link): 6:04 AM (0) comments

Wednesday, September 30, 2009

Word finds a new way to break my files 

Word never fails to surprise me. Every day I work with it, it finds new and creative ways of breaking my documents.

Today, I was working on a large, fairly complex specification document. I finished all my edits and created a PDF of the file. As I reviewed the PDF, I noticed that all my graphics were gone, replaced by "Error! Objects cannot be created from editing field codes." I've never seen this error before. I have not edited these graphics or their field codes.

The objects were Visio diagrams, and not linked to the original graphics. I have no idea why this happened, or when. The only way I could fix it was to re-insert the graphics into the document. Fortunately, there were only six of them.

At least it didn't happen on the documents I was working on yesterday, when I had a really tight deadline that I just made.

I submitted this to the word-pc mailing list and got several responses. Most suggested that the linking to the files had broken somehow, possibly by moving the files, except that I don't think the files were linked - I don't usually do that because files do get moved around and emailed to people. Another person suggested a registry key problem.

In any case, the file is fixed now, and I'll have to make sure I look for missing graphics in the future, when I create PDFs from these specifications. (I did search on "Error" and "Reference" in the Word file before I created the PDF, to look for bad cross-references, but this was a new error to me).

Labels: ,


// posted by Keith, on (permanent link): 6:52 PM (1) comments

Simple HTML tooltips 

Tooltips, those little yellow popup text windows, have been a feature of help in Windows for some time. WritersUA has published an article by Dave Gash showing how, with the aid of a couple of open source scripts, you can easily implement them in your HTML pages.
A developer friend of mine working on a Web app for a Los Angeles client had asked if I knew of a handy script that would display small amounts of help text -- "popups, expanders, or some such hooey," as he delicately put it -- for his form elements. I promised to look through my vast library of scripts and get back to him straightaway, then resumed work on my own contract and promptly forgot about the entire conversation. Not deliberately, of course; I just didn't make a note of it. And for some reason, if I don't write things down, they forget me.

The following week I was on my mobile phone provider's site looking up some call statistics when my mouse brushed across a tiny question mark icon next to an input field, and some help text appeared. Well actually, it didn't simply appear, it gradually faded into view. And it wasn't just a couple of words, it was several lines long. And it had a border and a background color. And rounded corners! And a little pointy descender like a speech balloon! It was awesome; I was transfixed; serendipity had struck.

I wasted no time scouring the page for the code reference (you gotta love "View Source"), and thereby discovered the script I soon provided to my developer friend and here present to you. To see it in action, just hover over any of the little "Top" graphics following this article's headings. Spiffy, eh?

Labels: ,


// posted by Keith, on (permanent link): 6:08 AM (0) comments

Tuesday, September 29, 2009

First time I've seen a video for online help 

Thanks to Cherryleaf Technical Authors Blog which links to the first video I've ever seen for online help - a Microsoft video promoting the online help for Windows 7. (The ad shows the help on Microsoft's web site, which is pretty good). The help is a lot better than the video, which is seriously cheesy, but at least their hearts are in the right place.

Labels: , , ,


// posted by Keith, on (permanent link): 6:08 AM (0) comments

Monday, September 28, 2009

How to network if you get laid off 

Here's a good article on how to use social networks to help you if you get laid off, and how to avoid some of the pitfalls.
1. Your blog is your resume. You need one and it needs to have 100 posts on it about what you want to be known for.
2. Remove all LOLCats from your blog.
3. Remove all friends from your facebook and twitter accounts that will embarrass you. We do look. If we see photos of people getting drunk with you that is a bad sign. Get rid of them. They will NOT help you get a job.
4. Demonstrate you are “clued in.” This means removing ANYTHING that says you are a “social media expert” from your Twitter account. There is no such thing and even if there were there’s no job in it for you. Chris Brogan already has that job and he’s not giving it up.

Labels:


// posted by Keith, on (permanent link): 6:03 AM (1) comments

Saturday, September 26, 2009

The Duct Tape Programmer 

Joel Spolsky's The Duct Tape Programmer is one of the more interesting articles I've seen recently. If you've worked in software development, you know the difference between the programmers who just like to get things coded and out the door and those who like to develop the architecture and the design and then polish everything until it's just exactly perfect. Here's what he says about the first type, the duct tape programmer.
Duct tape programmers are pragmatic. Zawinski popularized Richard Gabriel’s precept of Worse is Better. A 50%-good solution that people actually have solves more problems and survives longer than a 99% solution that nobody has because it’s in your lab where you’re endlessly polishing the damn thing. Shipping is a feature. A really important feature. Your product must have it.

One principle duct tape programmers understand well is that any kind of coding technique that’s even slightly complicated is going to doom your project. Duct tape programmers tend to avoid C++, templates, multiple inheritance, multithreading, COM, CORBA, and a host of other technologies that are all totally reasonable, when you think long and hard about them, but are, honestly, just a little bit too hard for the human brain.

Sure, there’s nothing officially wrong with trying to write multithreaded code in C++ on Windows using COM. But it’s prone to disastrous bugs, the kind of bugs that only happen under very specific timing scenarios, because our brains are not, honestly, good enough to write this kind of code. Mediocre programmers are, frankly, defensive about this, and they don’t want to admit that they’re not able to write this super-complicated code, so they let the bullies on their team plow away with some godforsaken template architecture in C++ because otherwise they’d have to admit that they just don’t feel smart enough to use what would otherwise be a perfectly good programming technique FOR SPOCK. Duct tape programmers don’t give a shit what you think about them. They stick to simple basic and easy to use tools and use the extra brainpower that these tools leave them to write more useful features for their customers.


I'm sure you could make a similar distinction among technical writers, although I'm a little too tired right now to come up with good examples. Toss in a comment if you think you can.

Labels: ,


// posted by Keith, on (permanent link): 10:56 AM (0) comments

Friday, September 25, 2009

Some good CSS tutorials 

As I start to work more with MadCap Flare, I am realizing that there is lot that I don't know about CSS (Cascading Style Sheets). I've been using them on my web site since about 1997 or 1998, but there have been many enhancements since then, and Flare seems to make use of all of them.

The HelpWare Group have a very useful page of tutorials on their web site, created by Frank Palinkas. They include totorials on building accessible tables and accessible navigation using CSS.

The page also includes tutorials on XSLT and API documentation, but it's the CSS tutorials that I'll be referring to, especially the one on tables, which are giving me headaches right now in Flare.

Labels: ,


// posted by Keith, on (permanent link): 6:05 AM (0) comments

Tuesday, September 22, 2009

Cost of not checking the documentation 

Sometimes bad documentation can be costly. Recently, Volkswagen missed putting a warning about air bag safety in an owners manual, and had to recall about 20,000 vehicles to replace the manual.
What did this little slip-up cost VW? Possibly hundreds of thousands of dollars, I expect, including these time and costs (I’m sure there are more):

* notify or respond to the relevant authorities (with all the internal legal department frenzy and crisis meetings when the issue was first identified)
* write and edit the press release and get it checked by Legal and the relevant authorities
* write and edit the insert and get it checked by Legal and the relevant authorities
* print the insert
* write a cover letter to all dealers
* mail out the insert to dealers
* assigning someone to take the calls from angry and confused dealers.

At the dealer end, there are these costs as a minimum:

* identify which customers purchased that vehicle model
* notify these customers
* mailing out the insert (or ‘installing’ it for them!)
* following up to make sure everyone who purchased one of these vehicles has been dealt with, and chasing up those who haven’t responded or been contacted
* assigning someone to take the calls from angry and confused customers.

Labels:


// posted by Keith, on (permanent link): 11:39 AM (1) comments

Monday, September 21, 2009

What's wrong with PowerPoint as an authoring tool 

Having recently been involved in a project where the parties involved decided to use PowerPoint as their primary writing tool, I can relate to this article: What's Wrong with PowerPoint as a Document Authoring Tool.
At the first meeting, the project leader announced she wants to continue the use of PowerPoint (PPT) as the document planning tool. Reasoning for this approach was in part because she and other team members already invested considerable time and effort in generating a 540+ slide deck representing data and messages to be in the regulatory document and PPT was a very familiar tool from extensive use in developing presentations.

I have to say we were mildly surprised by the demand to use PPT as the primary tool to plan and outline such a large, complex document. We have encountered other organizations using PPT for document planning purposes, but never on such a large scale. On the surface, the choice of PPT as the tool to produce initial draft documents seems reasonable. It is familiar to many, provides an authoring environment that produces output that can appear on screen as an outline, can be commented on in oral or remote review, and can be easily augmented and updated. All of these apparent benefits would support an argument for using PPT as an outlining tool to plan any and all documents. However, the use of this tool does not readily scale to developing large, complex technical documents.

Labels:


// posted by Keith, on (permanent link): 11:57 AM (1) comments

Sunday, September 20, 2009

Overview of DITA 1.2 

The latest version of DITA (Darwin Information Typing Architecture), DITA 1.2, is close to release. Here's a presentation (PDF), that covers the key features of the new release.

Labels: ,


// posted by Keith, on (permanent link): 7:26 PM (0) comments

Some more web apps 

The migration of software to the cloud continues apace. LifeHacker has a review article listing 10 of their favourite web applications. Out of the 10, there are several that a technical writer could use, especially Lovely Charts, the Aviary Suite, and ScreenToaster.

Labels: ,


// posted by Keith, on (permanent link): 10:00 AM (0) comments

Thursday, September 17, 2009

Getting content into and out of wikis 

We've been using a wiki at work for more than a year, and it's gradually getting adopted more widely across the organization. I have to admit that I have mixed feelings about this - it's good that people are making more documentation available, but a wiki isn't necessarily the best platform for some types of documentation, especially when you want to reuse or repurpose some of the information.

While it's pretty easy to get information into a wiki (we have a decent Word macro, for example), getting information out and into other formats is another matter. I tend to think of a wiki as something like a black hole - information goes in but doesn't come back out (other than by Hawking radiation, anyway, randomly and one quanta at a time).

Sarah Maddox has done us all a service by compiling a detailed list of tools for converting information to and from wiki format. If you have a corporate wiki, this is going to be an essential resource.

For the past couple of months I’ve been writing myself notes whenever I see mention of such a tool. Now I’ve added a bit of web searching to the mix. Here’s the resulting motley collection of tools that convert to/from wikis to/from wherever/whatever. It’s by no means complete, its order is decidedly random, and it focuses on Confluence and MediaWiki more than on other wikis, because Confluence is the wiki I use and MediaWiki is a biggie. If you know of other tools not mentioned here, I’d love it if you add a comment to this post.

Labels: ,


// posted by Keith, on (permanent link): 11:52 AM (0) comments

Thursday, September 10, 2009

DITAInformationCenter 

One of the problems with using DITA and the DITA Open Toolkit has been getting everything set up and running properly, and then finding the best, most recent documentation. That's gotten a lot easier, at least if you're a Windows user, with the release of the DITAInformationCenter.
The DITAinformationcenter is a learning and prototyping package that
contains:
- XHTML and PDF versions of the documentation
- DITA Open Toolkit 1.5 (current beta level)
- PHP interpreter 5.1.4
- A number of PHP-based debugging, editing, and reporting tools
- Two sets of sample DITA projects: garage and grocery shopping
- A README file explaining how to install and use the package
- DITA source files for the documentation (.zip file)

If you've looked at the DITA Open Toolkit User Guide in the past some of
this will sound familiar. What's new is that the key tools that will get
you started with DITA and the Toolkit are packaged together as a Windows
.msi file (easy to install and use); the documentation and tools have been
thoroughly updated, streamlined, and improved; and the package works and
has been tested at the Toolkit 1.5 level (although the content and tagging
do not yet contain 1.5-level features).

Labels: ,


// posted by Keith, on (permanent link): 11:42 AM (0) comments

Thinking Outside the Book, part 2 

Last night, I went to a Toronto Wiki Tuesday meetup to hear my co-worker, Scott Nesbitt, give a presentation, Thinking About the Book, about using wikis for documentation. About 20 people were on hand, hanging off Scott's every word, and treating him to rounds of rapturous applause and many rounds of beer after (well, I'm not sure about the last, because I left before he did).

Scott knows much more about wikis than I do - he's the person who introduced me to them, and his presentation covers a lot of ground. You can view it, along with the slide notes, which you will need, on his company's web site.

There was a lot of interaction with the audience during the presentation - I actually found it a little annoying at times - but it was nice to see an engaged audience and Scott handled it well. As far as I could tell, most of the audience weren't technical writers, and some weren't very familiar with wikis.

I'll probably go back for more meetings. The Groundhog Pub (Sherbourne and Bloor) is a congenial place too - the downstairs meeting room is ideal for this type of meeting and they have a reasonable selection of beer and pub food.

Labels: ,


// posted by Keith, on (permanent link): 6:08 AM (0) comments

Tuesday, September 08, 2009

Good indexing resource 

Indexing is one of those things that most writers have to do but often put off until the very end of a project when there's never time to do it properly. Seth Maislin is a professional indexer and his site has many articles that will help you to improve the quality of your index. He also offers tips on various indexing techniques, such as using Excel to build an index. Thanks to Cybertext Newsletter for the pointer.

Labels:


// posted by Keith, on (permanent link): 11:53 AM (0) comments

Adobe apologizes for poor customer support 

Things must be bad in Adobeland right now, because Adobe has posted a letter from Lambert Walsh, Vice President - Technical Services apologizing for their poor customer support. Abobe's customer support has never been something to write home about, but it's obviously been going downhill recently if they've received enough complaints that they have to make a public apology.

I should contrast that with the suppport I've gotten from MadCap software, who have resolved both of the issues I've raised with them. One issue appeared to have been missed, but wwas quickly resolved when I followed up, and the other was resolved in a couple of days (which is what I'd expect on our Bronze support plan). The MadCap forums have also been a good source of support from the user community.

Labels: , ,


// posted by Keith, on (permanent link): 6:08 AM (0) comments

Monday, September 07, 2009

Thinking Outside the Book 

My co-worker, Scott Nesbitt, will be giving a presentation called "Thinking Outside the Book" at Toronto Wiki Tuesdays, tommorrow evening, September 8th. Details here. Scott has been making extensive use of our wiki at work, and it should be an interesting presentation.
In this talk, Scott Nesbitt will explore the constantly evolving role of wikis in the creation and distribution of documentation. Drawing on a number of real-world example, Scott will discuss:

* The benefits of using wikis for documentation
* How both Open Source projects and firms of varying sizes use wikis to deliver documentation
* The technologies used to get content into and out of wikis
* The pros and cons of involving your community of users in the documentation process
* When a wiki might not be the best choice for delivering documentation

I plan on attending and will likely post a report here.

Labels: ,


// posted by Keith, on (permanent link): 10:51 AM (0) comments

Monday, August 31, 2009

STC Online Certificate Courses 

The STC (Society for Technical Communication is now offering several online courses, which will let you earn a certificate at the end of the course. They all look like good solid courses, and are being presented by top-flight professionals, including Sharon Burton, Bernard Aschwanden, Leah Guren, and Saul Carliner.

I took Saul Carliner's Technical Communication Management course as one of the pre-conference workshops at this year's STC Summit in Atlanta. It was probably the best technical-commication-related course that I've taken, and I will personally attest to both the quality of the course material and the presenter. If you are a technical communications team leader or manager, or planning to become one, take this course. You will not regret it.

I should also add that I've taken courses from Bernard Aschwenden and attended several of Sharon Burton's onilne webinars from MadCap Software. Both are highly knowledgeable and skilled presenters and their courses should be well worth the price.

This is something the STC should have done a long time ago, but although they may be starting late, they're off to a strong start.

Labels:


// posted by Keith, on (permanent link): 8:50 AM (0) comments

Monday, August 24, 2009

Documentation review checklist 

Here's a documentation review checklist that was put together as part of a class at Purdue University. It's pretty thorogh and goes beyond the basic appearance stuff that you often see in checklists.
The following "check-list" of items is meant to help testers focus their energies during documentation review on certain key characteristics of successful software documentation. You'll probably recognize a number of these from what we've covered so far. You're not required to turn in a completed check-list -- but I would like you to incorporate it into the feedback that you give the writer regarding his or her documentation.

Labels:


// posted by Keith, on (permanent link): 6:01 AM (0) comments

Monday, August 17, 2009

Analysing a car manual 

Here's a very funny lexical analysis of a car manual - just what is the writer of the manual really telling us and what can we learn from his or her word choices?
The Knee Impact Bolsters help protect the knees and position you for the
best interaction with the airbag.

You don't know it, but all the time you're sitting there staring into space
you're being positioned for an "interaction" with the airbag. In
anticipation of this explosive event, the Knee Impact Bolster performs a
kind of foreplay on you, whispering intimately, "Move your leg a little
bit. No, higher. There. That's better."

The manual goes on about airbags, rightly sensing that their recent mention
in the news calls for reassurance. Airbags can abrade you when they
inflate, and the language on this subject hits just the right tone:

The abrasions are similar to friction rope burns or those you might get
sliding along a carpet or gymnasium floor.

The chumminess disarms us, taking us right back to our school days. It
seems to say, "Remember the time big-mouth Sally dared you to slide down
the rope in the gym and you were still mad about what she told Judy at the
party so you slid down fast just to show her? Remember the rope burn you
got? That's what an airbag abrasion feels like."

Labels: , ,


// posted by Keith, on (permanent link): 11:45 AM (0) comments

Saturday, August 15, 2009

Army to wikify field manuals 

The U.S. Army has started a program to convert its field manuals to wiki format, in the hopes that soldiers will use their battlefield experience to improve them. This makes a lot of sense, especially as the "up or out" program has resulted in a lot of experienced soldiers being forced out because they weren't suitable for promotion.
Yet the Army seems willing to accept some loss of control. Under the three-month pilot program, the current version of each guide can be edited by anyone around the world who has been issued the ID card that allows access to the Army Internet system. About 200 other highly practical field manuals that will be renamed Army Tactics, Techniques and Procedures, or A.T.T.P., will be candidates for wikification.

As is true with Wikipedia, those changes will appear immediately on the site, though there is a team assigned to each manual to review new edits. Unlike Wikipedia, however, there will be no anonymous contributors.

Labels: ,


// posted by Keith, on (permanent link): 12:46 PM (0) comments

Friday, August 14, 2009

Get all 100K Unicode characters into your documents 

Cybertext Newsletter posts about a simple application (4 MB, run from a thumb drive) that catalogs all Unicode characters. You can easily view and search to find the specific character that you need and insert it into your document.
BabelMap is a free downloadable EXE (just under 4 MB) you can stick on a thumb drive or on your desktop. It contains all 100,000-plus Unicode characters AND it is searchable. It’s available from: http://babelstone.co.uk/Software/BabelMap.html

Labels: ,


// posted by Keith, on (permanent link): 11:30 AM (0) comments

Why you need technical writers early in a project 

Ben Minson explains why you need technical writers early in a project. This is something I've been trying to convince people at work for years, with some linited success. He makes a very good case.
At the start, the project team, users, and support need a common vocabulary so as to communicate clearly. I’ve discovered that one of the dangers of Agile methodology, if not mitigated by a clear glossary created at the beginning, is that due to contact with the developers, users start picking up their terminology. This can result in overly technical terms being introduced into the interface or in a discrepancy between the words that support agents and customers use. For example, I recently heard a coworker tell a user that “we call that” function a certain thing, when that was the first time I had ever heard that term. I hadn’t used it in the documentation, nor did it appear anywhere in the interface.

In such cases, in order to be clear, the technical communicator has to choose certain terms to use consistently in the documentation, but an inherent inconsistency results because not all users are following that same usage. If the technical communicator is included at the beginning and can set out the terminology then, confusion will be reduced.

Even if there is little risk of technical jargon slipping into the users’ vocabulary, the functions of the product need to be named. Do you use the term delete or remove? Box or frame? Book or folder? Edit or update? If we don’t pick one and use it but instead use different terms interchangeably, users may think they are different functions within the software.

Labels:


// posted by Keith, on (permanent link): 6:48 AM (0) comments

Thursday, August 13, 2009

Everybody needs an editor 

As David Farbey points out, everybody needs an editor - especially if you're Sarah Palin. Farbey's post is a good overview of the different types of editing, and why they're necessary.
Many people think that all an editor needs to do is to proofread their otherwise perfect prose. This sort of work, checking spelling and punctuation, and checking that a manuscript conforms to house styles and conventions, is the work of the copy-editor. A different function is performed by a researcher or fact-checker. In the Vanity Fair example, someone has checked which President had said, or not said, something memorable, which clearly hadn’t been done by Ms. Palin or her staff. Not checking facts can get writers into serious trouble, particularly if they mis-quote someone, give an incorrect attribution, or get facts wrong.

The most obvious corrections in the Vanity Fair are not copy-editing or fact checking, but are more substantive edits. Someone has taken the trouble to improve the style, clarity and vocabulary of the original speech while doing their best to maintain the meaning and intention of the original author. This is the most difficult and perhaps the most important type of editing, which helps an author express their ideas in a clear and unambiguous way. The editor can also ensure that the resulting article is written in a way that is most suitable for the intended audience.

Labels: ,


// posted by Keith, on (permanent link): 11:51 AM (0) comments

Tuesday, August 11, 2009

User interface style guides 

Here's a compreshensive list of user interface style guides, including guides from Apple, Microsoft, and Sun, as well as guides for various operating systems and classes of devices (such as mobile phones).

Labels: , ,


// posted by Keith, on (permanent link): 11:31 AM (0) comments

Thursday, August 06, 2009

IBM Style Guide 2009 

Back in my first full-time technical writing job, I worked for a company called SEI that mostly did work for IBM. As a consequence, I got a copy of the IBM Style Guide, which I still have (mostly for sentimental value). IBM has changed it's writing technology and writing style since them (think DITA), and their style guide has been updated as a result. If you want a copy, you can download the PDF from the The Writer's Rough Guide to Everything Flare blog.

If you'd rather have a web-based style guide for reference, the blog also has links to the Economist's and Guardian's style guides.

Labels: ,


// posted by Keith, on (permanent link): 6:06 AM (2) comments

Monday, August 03, 2009

STC's Notebook 

The STC (Society for Technical Communication) has a new blog - STC's Notebook.

The Society for Technical Communication welcomes you to its newest publication: STC’s Notebook. This blog will house relevant information for STC members and those interested in technical communication. New stories and articles will be added frequently and the blog will grow and change to meet the Society’s needs. The blog will replace News & Notes, but all of the articles historically captured in the newsletter will now be posted in a timelier manner to ensure up-to-date information delivery. STC’s Notebook will function as a consistent stream of information about and for the Society. Please feel free to comment on posts and participate in this social media platform. Visit STC’s Notebook for upcoming articles and posts, and be sure to subscribe to the RSS feed to receive notices of new blog postings.

Labels:


// posted by Keith, on (permanent link): 8:09 PM (0) comments

Anne Gentle's book on social networking and documentation is out 

Anne Gentle's book, Conversation and Community: The Social Web for Documentation is now published. Anne says:

I’m so pleased to tell you that my book is available now from Amazon.com and BarnesandNobles.com and for sale in Austin, Texas at BookWoman on North Lamar. Published by XML Press, this book was fun to write, difficult to finish, and a dream come true for me, a kid who read 500 books in a school year in the second grade. I love books and I love this book especially. But I do want to keep improving it with blog entries here and responses to honest and thorough reviews, even negative ones.


It's published by XML Press and they have an interview with Anne on their web site. I won a copy of the book at the STC Summit and I'll review it here once I receive my copy.

Labels: ,


// posted by Keith, on (permanent link): 11:45 AM (0) comments

Thursday, July 30, 2009

Why the STC should put its print magazines online 

With the STC going through a financial crisis, many people (myself included) have suggested that the STC should move its magazines, Intercom and Technical Communication to an online format. This would have many benefits, especially for Intercom, as outlined in this post by Tom Johnson, who examines the many reasons why magazines should consider moving to online publication.
As part of the solution to STC’s financial situation, some members have talked about making Intercom an online magazine only, removing the printed version that is mailed out to thousands of members each month. Many people think the move from paper to online would be a tremendous blow to the STC, one that would significantly decrease member value towards one of STC’s most attractive assets.

Sometimes people talk about this potential move, from print to an online format, with a doom and gloom that would make you think they’re foreclosing on a house or planning a funeral for a close relative or giving up their children for adoption.

When I hear these discussions, it blows me away because I can hardly believe what I’m hearing. I admit, the look and feel of paper can provide a comfortable reading experience if you’re immersed in a 200 page novel lying on your bed on a rainy day. But the Intercom and other professional magazines or journals are not novels. With professional publications like these, the online format better matches the reading behavior of the audience. In fact, online formats provide more than a dozen advantages that print formats lack, including everything from interactivity to portability, feeds, metrics, multimedia, and more.

I still like reading print magazines, but unlike Tom, I don't have a portable device like an iPhone or Blackberry that I can use to read online. I usually read Intercom on the GO Train on the way to work. But I's still rather see it go to an online format - the benefits are too many too ignore. As for Technical Communication, there might be some benefit for printing copies for libraries, but certainly general members should get an online version.
Update: On the Palimpsest blog, Sarah O'Keefe has a lengthy response to Tom Johnson's post. For part of it, she plays devil's advocate, looking at ways in which a print edition might be superior to an online format. She then looks at what the STC could potentially save by going to online publication.
have been told that STC will lose advertising income if the magazine goes online only. I would agree that advertisers will pay less for online advertising as opposed to print advertising, but surely the advertising income would not drop all the way to zero. Let's assume, however, that it does. The best estimate I have for advertising income is $143,159 (from Paul Bernstein's detailed cost breakdown on the STC Ideas forum, accessible here to registered members of the forum).

So, even if advertising drops to zero, we have a net positive of $150,000 from moving online. Implementing an XML or HTML-based magazine for the first time will cost a lot less than that. Therefore, the return on investment appears quite compelling.

Labels:


// posted by Keith, on (permanent link): 7:58 PM (3) comments

Wednesday, July 29, 2009

Adobe on FrameMaker/RoboHelp integration 

Adobe's Technical Communication blog has a long post about how they've updated the integration between FrameMaker and RoboHelp in the Technical Communication Suite 2. I did look at this briefly when I was beta testing Frame 9, but due to some installation issues I had with the beta, I never did get it to work. Based on what's in the post, it looks like they are making true single-sourcing much easier with this release.

Labels: ,


// posted by Keith, on (permanent link): 11:45 AM (0) comments

Thursday, July 23, 2009

Do screen captures make sense? 

On the Content Wrangler site today, a good article about whether screen captures still make sense in most user documentation. This is a particular problem for those using XML-based tools, especially DITA, which can be inflexible in the way they handle graphics.

When I first started writing user guides, I included many screen captures. However, I've since greatly reduced my use of screen captures, and now have only a couple of manuals where I use them to any degree. These are aimed at relatively unsophisticated uses and have a fairly complex interface, so I think the captures are helpful. Even then, I've cut the numbers back to just the places where I think they will really help the user understand how to use the interface.

In most of my other manuals, I've dropped screen captures without any complaints from the users.

So, according to the article, when does it make sense to use screen captures?

Reasons for including screen captures

* A picture is worth 1000 words. If you can describe interface elements (like a wizard panels or dialog boxes) with the aid of a screen capture, readers can interpret the supporting prose more easily. Screen captures also help to minimize prose, as writers don’t need to describe interface elements in detail (they can simply point to a picture).
* Screen captures can help keep the user’s eyes focused on documentation for longer periods of time (rather than switching back and forth between doc and interface, to make associations), which helps make it more readable.
* If a user does not have the application interface available when reading the documentation, screen captures provide the reader’s only visual image, and therefore might be critical to establishing an understanding of the surrounding prose. Historically, even in cases where the application is available, users have welcomed screen captures because they are helpful if used and not harmful if skipped.

For reasons not to use screen captures, see the article.

Labels:


// posted by Keith, on (permanent link): 10:52 AM (0) comments

Wednesday, July 22, 2009

Did PowerPoint contribute to the Columbia disaster? 

Edward Tufte, well-known for his pioneering work on information design and analysis, has an online excerpt from his book, Beautiful Evidence, in which he examines the PowerPoint presentations created at NASA during the Columbia mission. He finds that the hierarchical structure imposed by PowerPoint may have contributed to the disaster by burying key information in lower levels of the hierarchy.

Unfortunately, his web site has blocked copying, so I can't excerpt the relevant portions here, so you'll have to read them for yourself. They're well worth reading and taking to heart. I will quote one brief passage from his conclusion:
Serious problems require a serious tool: written reports. For nearly all engineering and scientific communication, instead of PowerPoint, the presentation and reporting software should be a word-processing program (emphasis his) capable of capturing, editing, and publishing text, tables, data graphics, images, and scientific notation. Replacing PowerPoint with Microsoft Word (or, better, a tool with non-proprietary, universal formats) will make presentations and their audiences smarter.

Labels: , ,


// posted by Keith, on (permanent link): 10:40 AM (1) comments

Wednesday, July 08, 2009

Modifying toolbars in FrameMaker 9 

Adobe's Technical Communication blog has posted an article about how to customize the toolbars in FrameMaker 9.
Earlier we used to have one .ini file ($FMHOME\fminit\fmtoolbr.ini) to define all the toolbars. Now the fmtoolbr.ini has been changed to a more modular architecture.

1. The toolbars now exist in the $FMHOME\fminit\toolbars AND , i.e. %appdata%\Adobe\FrameMaker\9\toolbars\. The toolbars present in the supersedes those present in $FMHOME just like the maker.ini. So, multiple users using one FrameMaker build may design their own toolbars by storing the toolbar files in their user area.
2. Also if one needs to add a new toolbar, he just can create another XML file and add its entry in fmtoolbar.xml. The usage of toolbars is defined in tag-description.xml.

Labels: ,


// posted by Keith, on (permanent link): 11:33 AM (0) comments

Monday, July 06, 2009

How the Web and blogs have changed publishing 

Here's an article that summarizes some of the ways in which the Web and blogs have changed publishing. It would be nice to see it extended to include Twitter.
Update: It works better with a link to the article ....

Labels: ,


// posted by Keith, on (permanent link): 11:32 AM (1) comments

Tuesday, June 30, 2009

Technical Writing 101, 3rd edition - a review 

Technical Writing 101: A Real-World Guide to Planning and Writing Technical Content, 3rd edition; Alan S. Pringle and Sarah S. O'Keefe, Scriptorium Publishing Services Inc., Research Park Triangle, NC, 2009, ISBN: 978-0-9704733-7-0, 328 p., $20.00 (PDF Download), $35.95 (paper)

Almost ten years ago, in my previous job, I was asked to train a co-worker to become a technical writer. She'd been working in our Marketing department, but her position had become redundant because of a corporate takeover. One of the books that really helped me was the first edition of Technical Writing 101. She was already a good writer, but the book introduced her to the specific requirements of our profession.

Since then a lot has changed. Think of just the last decade: Web 2.0, social media, DITA, Google, YouTube and rich media, to name just a few. And the corporate environment has changed, putting greater demands than ever on writers to be efficient and productive. This edition of the book has been thoroughly updated to cover these new technologies and the demands they make on writers.

As you'd expect, the core of the book covers the basics: writing, procedures, using graphics, editing and being edited, and indexing. But, as most new writers quickly find out, writing is only a small part of the job. The book starts by explaining the many things that writers do other than writing. The second chapter explains the importance of templates and structure, and the third discusses documentation plans and outlines, both critical tools in a writer's arsenal. (A sample documentation plan is provided as an Appendix). Only one relatively short chapter is devoted to tools, probably appropriate considered many writers' tendency to obsess over tools rather than content.

Later chapters discuss more advanced topics, ones that really exist for most writers when the first edition of this book came out - structured authoring (XML and DITA), and Web 2.0 (wikis, blogs, and other social media). The final chapter is about how to get your first job as a technical writer.

Although Technical Writing 101 is aimed at new writers, topics are covered in enough detail that more experienced writers can use the book as a refresher or a reference to unfamiliar topics. For example, the indexing chapter is 15 pages long and covers most of the things any writer would need to know about the subject. The chapter on structured authoring would be a good introduction to anyone thinking about switching from unstructured authoring to DITA. Many sections include short sidebars providing tips and best practices; for example, the Getting Information chapter has a list of 30 suggestions for getting information from developers - a task that many writers, beginning and experienced, find difficult.

Technical Writing 101 would be an excellent choice as a text in college-level technical communication programs. It's hard to imagine anyone coming up with a better introduction to the field for new writers. But even experienced writers can benefit from reading this book. It contains a wealth of tips and practical information. If you have a manger who's not a writer, give them a copy. It might help them appreciate your job a little more.

Contest note: Today (June 30) is the last day to enter a draw for a copy of this book.

Labels: ,


// posted by Keith, on (permanent link): 6:03 AM (1) comments

Monday, June 29, 2009

Content typology: Getting a handle on your content types 

The Content Noob has a long post about content types and why you should be looking at them. If your using a content management system or if your practicing topic-based authoring, you'll need to know about content types, and this article is a good introduction.
A Type is the basis, the foundation, the primary class, or the standard, upon which all instances of something are modeled, and against which all examples of that thing are compared. A Type describes the thingness of a thing, which is recognizable, no matter how much variation is evident among all the things.

For example, mammals are a particular type of animal. Since we were in primary school, we have recognized the fundamental characteristics of that type: Mammals breath air, they bear their young live, they nurse their young, and they have fur of one kind or another. The mammalian type, however, is almost infinite in its diversity throughout the world, and there are even some examples that “violate” the type—like platypuses. Yet as a type, mammals are pretty clear, whether they walk, swim, fly, or climb.

In exactly the same way, every piece of content on your website (for that matter, every piece of content) has a primary type. Quick examples include articles, press releases, product specifications, photographs, graphic charts, customer reviews, blog posts, demonstration videos, support manuals, login splash screens, order forms, et cetera ad nauseum. In one way or another, everything on your site is content, so everything has a content type.

Labels: ,


// posted by Keith, on (permanent link): 11:31 AM (0) comments

Why still do PDF manuals? 

Mike Hughes of UXMatters has a long article looking at the reasons people usually give for producing PDF manuals and explaining why other online formats are better. I'm one of those people who's still producing PDF versions of some of our manuals, although I do plan on trying to make the online versions the primary documentation, now that we have MadCap Flare.
Let me describe a familiar user assistance experience. A user installs a new application, and when the user wants Help, the application directs her to the user documentation on a Web site or CD-ROM. What the user finds there is a PDF file containing the manual—or a collection of PDF files, representing a library of manuals, including a user guide, configuration guide, troubleshooting guide, and various references. And the layout of each of these PDF manuals is exactly the same as if it were a printed book. This raises an interesting question: If we’re giving manuals to users to read online, why do we design and write them for paper?

I’m not down on every use of PDF files online. Campus maps, article reprints, and my aunt’s Christmas letters all work quite well as PDF files. What I want to challenge in this column is the use of PDF files for distributing user assistance online, in the form of large books.

Labels: ,


// posted by Keith, on (permanent link): 6:05 AM (0) comments

Wednesday, June 24, 2009

Win a free copy of Technical Writing 101 

Scriptorium are having a draw for two copies of their updated, third edition of Technical Writing 101. I'm working on a review of this now, and it should be up here in a few days. Trust me - even if you're an experienced writer, you'll want this book, and if you're new to the field, it'll be a godsend.

Labels: ,


// posted by Keith, on (permanent link): 7:03 PM (0) comments

STC Toronto annual meeting 

Last night, I attended the annual meeting and dinner of the Toronto chapter of the Society for Technical Communication. I've been a member since 1992, but this was the only chapter event I made it to this year. (Usually, I get to two or three meetings). Instead of the traditional wine and cheese evening, the AGM was a dinner at the Mandarin Chinese restaurant, with the dinner subsidized by the chapter. Turnout was good; the chapter had reserved fifty seats and they looked filled (and even more filled after everyone stocked up at the very decent buffet).

Outgoing chapter president Bernard Aschwanden gave a presentation on the current state of the STC (not good) and the local chapter (doing well). He mentioned that one option the STC was considering was taking funds from the local chapters, something they are legally entitled to do. Apparently some larger chapters are sitting on substantial ($100,000) nest eggs. The Toronto chapter would not support this. While they are prepared to give money to the STC, if asked, they would prefer to see the money given to members in the form of free attendance at the annual conference, for example.

The Toronto chapter has been using some of its funds in this way. This year they helped several members by paying part of their conference costs, and they do pay the costs to send the incoming chapter president to the annual conference. (This is a good idea.) The chapter has also been going from a straight meeting format to what they call a 5 and 5 model - five program events (career day, technology trends day, and so on) and five social events, held in different areas to accommodate the widely spread out membership. They've also used some of their money to help out some of other smaller, Southern Ontario chapters.

The meeting also included a short talk by Ann Rockley, who lead a revival of the chapter in 1985, about the history of the chapter - I didn't know it had been around since the 1950s. At its peak in the early 1990s there were over 600 members. Membership has since fallen to about 350, still a healthy number, and with the good management shown by the chapter so far, they are in a good position to continue on even without the aid of the larger organization.

Incoming chapter president Anna Parker-Richards talked about how they are planning for the coming year and discussed some of the things they've done to streamline their operations. They're also apply project-management techniques to their own affairs, including tracking metrics for the success of various programs and writing up a set of best practices to help new officers.

All in all, I was quite impressed. The Toronto chapter is financially sound and appears to be well run, and focused on helping its members. I'll be looking forward to seeing what they come up with in the coming year.

Labels:


// posted by Keith, on (permanent link): 6:36 AM (0) comments

Tuesday, June 23, 2009

STC floundering? 

It's been pretty clear over the last few months that the Society for Technical Communication (STC) is facing some hard times. Attendance at this year's conference was way down (below 1,000) and memberships, the other major source of revenue, are falling too. The STC has been sponsoring a series of webinars to discuss future directions and has acknowledged that unless they can turn things around, and quickly, the organization will run out of money in a couple of years.

Needless to say, this has generated a fair amount on discussion in the blogosphere. In the last few days, I've seen lengthy and thoughtful posts from Sarah O'Keefe at Palimpsest, Tom Johnson at I'd Rather Be Writing, and Paul Pehrson at Technically Speaking.

Some common themes are emerging. The obvious place to start economizing is with the print publications - Intercom and Technical Communication. There may be some value to having a print version of Technical Communication for libraries, but Intercom should be online only. It should also be open to non-members to serve as a vehicle for promoting the role of technical communication. The organization also needs to seriously revamp its web presence - the stc.org web site is dated and hard to navigate, for example, and make more use of emerging social media technologies.

Despite the fact that I found this year's Summit a very worthwhile experience, the money put into the conference could probably be better spent beefing up the programming at local chapters, who are, after all, one of the primary sources of new and returning members.

I'll be attending the Toronto chapter's annual meeting tomorrow night. I'm sure there'll be a lot of discussion there about the future of the STC. (From what I've been told, the Toronto chapter is one of the few financially solvent chapters, despite a decline in membership since the beginning of the decade).

I would hate to lose the STC. It was really important in my development as a technical writer, and I still find it worthwhile. However, it's not essential - the rise of the Internet, with the World Wide Web and social media, has provided many alternatives for finding information and networking with other writers. At one time, the STC was pretty much the only game in town - it's not now, and if the people running the organization don't realize this and start doing something about it now, it will die away.

Labels:


// posted by Keith, on (permanent link): 6:07 AM (2) comments

Monday, June 22, 2009

Microsoft Help3 resources 

Microsoft announced Help3, a new help system designed to work with Visual Studio 2010 applications. They gave a presentation on it at WinWriters, but I haven't heard anything from that. Now CyberText Newsletter has a post with some links to resources on Help3.

Labels: , ,


// posted by Keith, on (permanent link): 7:00 AM (0) comments

Thursday, June 18, 2009

Flare 5 DITA features reviewed 

One of the major new features of MadCap Software's Flare 5 is DITA import and export. Scriptorium's Palimpsest blog has a two-part review of Flare's DITA capabilities (Part One and Part 2)

The import feature seems to work pretty well, as long as you haven't specialized DITA (which Flare doesn't yet fully support). This capability should give DITA authors a fairly easy way to generate full web-based help systems from DITA source files. (WebWorks ePublisher has offered the same ability since 2007), as well as PDF output that's better than that offered by the DITA Open Toolkit.

I haven't yet seen a discussion of Flare's DITA export feature. Given that MadCap didn't demo it in the webcast of Flare's new features, I suspect that it's more complex to use than the import, which appears pretty straightforward.

Labels: , ,


// posted by Keith, on (permanent link): 6:06 AM (2) comments

Wednesday, June 17, 2009

How to avoid extinction as a technical communicator 

Unless you've had your head buried in the sand (deep enough that you can see the Sydney Harbour bridge), you've probably noticed a couple of things. One is that the economy is in pretty bad shape. Another is that the nature of the technical communication profession is changing - it's about a lot more than turning out PDFs to put on the release CD. And maybe your developers have set up a wiki, and your managers are wondering just what value you're adding to the product.

I've talked about this with some other writer friends and we've come to pretty much the same conclusion that Ellis Pratt did, which Tom Johnson elaborates on in this excellent article, How to Avoid Extinction as a Technical Communicator.
In a career development workshop at the TransAlpine Conference in Vienna, Ellis Pratt, one of the founders of Cherryleaf, argued that technical communicators may eventually become extinct if they keep using the same methods and formats to deliver information.

Although there will always be a need for people to explain technical material non-technical people, Ellis said, others may be doing it instead, through the formats users prefer. To survive, technical writers may need to morph into content strategists, managing the information in a systematic way rather than merely creating it.


This may not be a realistic goal for everyone - as Tom points out later in his article, not everyone has access to the newest technologies behind their corporate firewall. Yet there are things that we can do - encouraging that all information is produced in a common, interchangeable format (such as DITA) is a good start.

It's one of the more interesting articles I've seen recently about where our profession is going, and based on the number of Tweets I've seen about it so far, I'm sure it'll generate a lot of comment and discussion.

Labels:


// posted by Keith, on (permanent link): 6:03 AM (0) comments

Tuesday, June 16, 2009

DITA 101 - a review 

DITA 101: Fundamentals of DITA for Authors and Managers; Ann Rockley, Steve Manning, and Charles Cooper; The Rockley Group, www.rockley.com, 2009, 138 pages, paper, $9.95 (download), $25.21 (paper)

Since its introduction in 2001, DITA (Darwin Information Typing Architecture) has become the dominant standard for structured authoring. According to a recent survey conducted by Scriptorium (results discussed in this presentation), about 70 percent of respondents working with structured authoring are either using DITA now or planning to on future projects. That's pretty impressive for something that wasn't much more than an inscrutable article in Technical Communication and some poorly documented Java/XSLT code eight years ago. Yet structured authoring represents only part of the technical communication field; according to the same survey, 29 percent of respondents are using structured authoring now, more than half plan to do by 2010. That means there are many potential users of DITA who are likely going to be searching for information about it sometime in the future.

One of the barriers to implementing DITA has been the state of its documentation. Like many open source projects, DITA's documentation is scattered and inconsistent. The documentation for the DITA Open Toolkit has improved dramatically in the last few years, but it still isn't up to the standard of most commercial projects. Comtech Service's Introduction to DITA, first published in 2006 and recently updated, offers a good introduction to getting started with the DITA Open Toolkit, but may be too technical for many writers, especially those who just want to use the DITA implementations that are now included in most major writing tools.

DITA 101: Fundamentals of DITA for Authors and Managers, a new book from the Rockley Group, provides a more readable introduction. Rather than explaining the nitty-gritty of how to use the Open Toolkit and XML, it focuses on explaining what DITA is (and isn't), and what are its benefits and pitfalls. Much of the books content comes from experience the members of the Rockley Group have gained in conducting training DITA and content analysis and management.

The book begins with a history of DITA and the use of XML in structured documentation, then looks at the benefits of structured authoring. The primary benefit is the ability to separate format from content, thus making it practical to reuse content in different contexts. The authors provide practical guidelines for writing structured content and discuss the different ways of reusing content, all before getting into a discussion of DITA itself. This is followed by a review of the DITA topic types, concept, task, and reference, with an explanation of the elements that make up these topics.

Planning is especially important in a DITA project and the book contains a chapter explaining the key steps, including a summary of the Rockley Group's unified content strategy (explained in much more detail in Rockley's other book, Managing Enterprise Content). The authors also spend some time discussing an issue that is often neglected when organizations move to a structured workflow - how the authoring process changes the organization and the effects it has on people's roles. One area that is given rather short shrift is content conversion - they recommend against it, but this may not be practical in organizations with a lot of legacy content. I would have liked a discussion of some of the issues and alternatives here.

The technology involved in implementing a DITA-based workflow can be quite complex and daunting. The authors provide a succinct discussion of the issues, including when and how to use DITA with a content management system.

A section called "The advanced stuff' looks at conrefs (which provide content reuse), conditional processing, relationship tables, and specialization, which is DITA's mechanism for customization. Finally, a set of Appendixes contain a reference to DITA topics and elements.

Although this isn't a long book (140 pages), it's full of useful information, tips, and guidelines. The Rockley Group is an industry leader in the area of structured authoring and content managment, and they've distilled a lot of their experience into this book. Writers contemplating a move to DITA should definitely read it, and give a copy to their managers, too. At the very reasonable price of $9.95 for the download edition, this book is a bargain.

Labels: , ,


// posted by Keith, on (permanent link): 6:04 AM (2) comments

This page is powered by Blogger. Isn't yours?