I should know better than to get involved in this one...
posted by Sarah
Kathy Sierra's Creating Passionate Users blog is one of my favorites. But her latest entry is entitled Why marketing should make the manuals!

Ugh.

Read the whole thing, and then let's chat. I'll wait.

Ready?

So.

Kathy and I do have some points of agreement. For instance:

• More resources should be allocated to user documentation.
• Attractive documents are better than ugly documents.

But then, I'm sorry to say that Kathy loses me.

"The brochure gets the big budget while the manual gets the big index."

Let's assume that you have a moderately complex product. The index is the most important part of the entire manual. Why? Because readers use the index to find information. If they can't find it, then from the reader's point of view, the information doesn't exist.

Indexes are good. The presence of an index does not mean that you have a big, boring book.

Next, we need to think about different types of documentation and how they are used:

• Tutorials and quick start guides are intended to be read sequentially and in their entirety. For these, it's important to hook users, provide them with a reason to keep reading, and make sure that the information is accurate, well-organized, and accessible. These documents, like marketing materials, are intended to persuade and inform.
  
• Reference documentation is intended to be read in pieces. The user is doing something with your product. They realize that they don't have a particular piece of information -- can I use an apostrophe in the last name field? They look it up in the reference documentation. Users do not read reference documentation from cover to cover. They dive in, get the information they need, and go back to their work. For reference documentation, it's critical to provide logical organization and multiple information access techniques (table of contents, index, related topics, alphabetical organization, hyperlinking in online documents, and so on). You can make reference documentation more engaging (for example, you can use entertaining examples), but readers do not want to read the whole thing.
• User documentation is generally task-oriented; it provides step-by-step instructions on how to complete a particular task. Often, the user documentation includes an introductory chapter that provides a conceptual overview of the product. You definitely want users to read this information. But again, most users will drop in, read about a task or two, and then go back to their work.

There are numerous problems that can arise when you create user documentation:

• Information is wrong. The information in the user documentation is incorrect; it does not match how the product actually works.
• Information is missing. The user documentation doesn't discuss a feature that is present in the product, or provides incomplete information.
• Information is poorly written. The content is hard to understand. Supporting graphics are non-existent or ugly.
  
• Information access is poor. The content is hard to find because the document organization is weird (or absent), the index is poor (or missing), and the page navigation (the book design) doesn't support scanning for information.
• Information is ugly. The content is no fun to read because the book design is lacking.
  

If you had to rank these problems in order, the last bullet would presumably not be at the top of the list. Wrong pretty information is not better than correct ugly information. And this brings us to the crux of the problem. When there aren't enough resources to create the documentation, the problem list gets triaged, and "make it pretty" is at the bottom of the list. In writing about Kathy's article, Darren Barefoot said this:

"User manuals get a bad rap because companies don’t devote enough resources to them. That money should be spent on thoughtful tech writers, trainers and support personnel who can make compelling training and support material." Keep Marketing Away From the Manuals | DarrenBarefoot.com

Investing in making product manuals more attractive is a good thing. But in most documentation groups, there are far more pressing problems that need to be addressed.

Let me also throw in another plug for accessibility. Technical documentation is often repurposed into multiple outputs -- print, PDF, HTML, and the like. Design-heavy books tend to be difficult to repurpose and often cause accessibility problems (for example, screen readers don't much like drop caps).

Finally, it helps to keep in mind that marketing deals with short documents -- two-page data sheets, ten-page white papers, brochures, and the like. Technical documentation is orders of magnitude larger -- hundred-page documents, thousand-page references. When you are publishing 5,000 pages every six months, it makes sense to consider the efficiency of a particular book design.
1:07 PM Permalink | |

 
Converting InDesign to XSL FO
posted by Sarah
This is so totally geeky.

RenderX - Products - Free Tools - Stylesheets for converting Adobe's InDesign INX documents to XSL FO

In English, I think this means you could design a document in InDesign, then save it as INX (InDesign Exchange format), and then convert that into XSL-FO. Which means you could rebuild your InDesign layout with XSL-FO.
4:59 PM Permalink | |

 
I resemble that remark
posted by Sarah
The Onion apparently has spies in our office:
Résumé Font Offends Employer | The Onion - America's Finest News Source (not completely work-safe)
5:36 PM Permalink | |

 
Jobs
posted by Sarah
(updated 8/31)

Scriptorium Publishing is hiring!

We're always looking for contract trainers.

For details, please read our jobs page.

(we have filled this position, too, 8/31) We also have a position open for a six-month, full-time contractor who would work as a consultant/trainer.

(we have filled this position, 8/12) Finally, we have a short-term (one-month) contract to work on FrameMaker-to-FrameMaker conversion. If you're an expert FrameMaker user and have experience converting from one template to another, please email me as soon as possible.

Contact information is on our web site.
4:27 PM Permalink | |

 
Our business case for self-publishing
posted by Alan Pringle
With the recent release of Publishing Fundamentals: FrameMaker 7 (formerly published as FrameMaker 7: The Complete Reference by McGraw-Hill/Osborne), we've had a few inquiries about why we chose to publish the book ourselves.

In the case of Publishing Fundamentals, the original publisher declared The Complete Reference out of print, but there was still a strong demand (well, strong from our point of view!) for the book. It wasn't a hard decision for us to reformat and reprint the book.

Beyond the immediate demand for Publishing Fundamentals, though, there are big-picture reasons why we publish books and workbooks through our publishing arm, Scriptorium Press:

• Financial. We've published books through mass-market publishers before, so we have a pretty good idea what kind of money authors can expect on books related to the technical publishing industry. The returns are surprisingly small, especially when you look at the money you make on each copy the publisher sells. We make more money when we print and distribute our own books, even after paying the costs associated with printing, distribution, and running an online store. (This is still true when we do smaller print runs on digital printers and incur higher printing costs on each copy.)
• Control. Publishing our own materials gives us ultimate control over content and design (and when to declare a book is out of print). We can put out a book that we think is best for our audience without dancing around suggestions from book project managers and proofreaders who may not know a lot about the subject matter of a book and therefore request changes that are not in the readers' best interest. (Not all book project managers or proofreaders are like this, of course.) On the flip side, publishing in-house means we have to do all the writing, editing, indexing, and production work ourselves. We are fortunate to have a group of people here who are well-versed in all facets of book publishing, so we have been able to handle all these tasks. We are not graphic designers, however, so we have enlisted the services of a graphic artist to design our book covers.
• Marketing. Because our clients are in the technical publishing industry, it is very helpful for us to have books and workbooks that prove we understand the publishing process. Showing a prospective client hard copies of our books with the Scriptorium Press logo on them is a powerful marketing tool. Also, readers of our books remember us and then come to us for more books or even consulting services. It's great when a reader also becomes a long-term client.

Does this mean everybody should rush out and publish their own books? Not at all. Just because you can publish your own material doesn't mean you should proceed with every book idea you have. We still complete outlines, marketing plans, and so on, for prospective titles to evaluate if a title can make it in the marketplace. We've also pulled the plug on a book or two when things weren't coming together as we expected. You also have to consider the costs associated with creating the text as well as publishing it. Overall, though, Scriptorium Press has been rewarding for us, and not just in a financial sense.
11:53 AM Permalink | |

 
That's one mystery of the universe explained
posted by Sarah
FrameMaker users are a loyal, occasionally even fanatical, bunch. The mystery has always been exactly why that is so. After all, there are lots of software tools out there, and many of them are prettier, faster, and cheaper than FrameMaker. But you don't hear a lot of discussion about the joys of Visio.

Madcap Flare, on the other hand, does seem to have that magic buzz. And finally, Kathy Sierra explains the issue:

When we talk about "best tool for the job", we should look not only at "best for the task", but also "best for those who must use it." (When the "best tool for the job"...isn't)

Kathy lays out three criteria for tool selection -- the match between the tool and the required tasks, the user's current expertise in the tool, and the user's enthusiasm for the tool. This explains a lot. FrameMaker is an excellent fit for typical tech writer tasks and many writers have expertise in the tool. It automates what can otherwise be drudge work in creating long documents--that's where the passion comes from.

It also explains why XML-based authoring is such a difficult sell. XML may be the best approach for content creation and management. It does not, however, take into account the writer's needs. Many of us got into writing because we get deep satisfaction from seeing our work on a printed page. XML-based systems often separate the writer from their results.

You write a topic and plug it into the system, but you don't get immediate feedback.
You don't see your page count go from 1 to 4 to 7.
You don't see the empty page fill with content.
You don't get to watch as your table of contents slowly grows.

With structured authoring, it can feel as though you're writing in a black hole.

Nonetheless, XML content has clear advantages over "regular" content, and the transition difficulties are short-lived. (Authors with at least one year of experience in structured authoring environments generally like them.)
8:27 AM Permalink | |

 
Bad news for WWP 2003 users
posted by Sarah
Quadralay has announced "end of life" for WebWorks Publisher 2003. Currently, you can see this announcement on the main support page.

Consensus appears to be that ePublisher Pro, which is now about a year old and labeled version 9.2, is really not yet ready for prime time.

This announcement is unlikely to make people happy.
4:36 PM Permalink | |