Random thoughts about publishing

icon Site Feed

Labels

Palimpsest

 

I should know better than to get involved in this one...

Thursday, August 31, 2006 — 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:
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:
There are numerous problems that can arise when you create user documentation:
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 | |

divider

 

Converting InDesign to XSL FO

Monday, August 28, 2006 — 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 | |

divider

 

I resemble that remark

Friday, August 25, 2006 — 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 | |

divider

 

Jobs

Wednesday, August 09, 2006 — 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 | |

divider

 

Our business case for self-publishing

Thursday, August 03, 2006 — 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:

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 | |

divider

 

That's one mystery of the universe explained

Wednesday, August 02, 2006 — 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 | |

divider

 

Bad news for WWP 2003 users

Tuesday, August 01, 2006 — 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 | |

divider


Scriptorium Publishing | Post Office Box 12761 Research Triangle Park, NC 27709 | (919) 481 2701 | info@scriptorium.com