Surprise! It's about quality.
posted by Sarah
(Scriptorium Publishing is a JustSystems Services Partner.)

On Monday, August 18, I delivered a webinar on making the transition from desktop publishing to structured authoring. This event was jointly sponsored by Scriptorium Publishing and JustSystems. The recorded version is available here (registration required).

During the presentation, we did some audience polling. And here, there were some surprises for me. We asked:

How are you authoring content today? (choose any)

• 31%, Word
• 14%, HTML authoring tool (i.e. Dreamweaver)
• 69%, Desktop publishing tool (i.e. unstructured FrameMaker, PageMaker, InDesign)
• 20%, Help authoring tool (i.e. RoboHelp, Flare, AuthorIT)
• 37%, XML authoring tool (i.e. XMetaL or structured FrameMaker)
  

Nothing too shocking here, although I was a little surprised to see such a high number for XML authoring in a session on how to transition to structure.

In poll 2, things got very interesting:

What is the level of authoring at your organization? (choose one)

9%, #1. Chaos. No consistency
4%, #2. Documents match on paper
16%, #2.5 We have a template and sometimes follow it.
60%, #3. Template-based authoring. Repeatable process for creating consistently formatted documents
10%, #4. Structured authoring. Programmatic enforcement of required organization

When I ask this question a roomful of people, it's rare to get an admission of level 1. I've never seen anything like 10 percent of a live audience choose number 1. Perhaps the relative anonymity of a webinar is a contributor?

We asked some questions about skillsets with nothing of particular interest to report. Finally, we inquired about the business driver for structure implementation:

What is your critical business driver behind looking to improve how you manage content?
(choose one main driver)

10%, Speed up time-to-market
30%, Improve satisfaction with customer-facing documentation
3%, Comply with regulatory requirements
12%, Reduce localization cost
27%, Improve staff productivity
13%, Reduce production cost
4%, Other

The surprise here was that, at least in this group, the most single common response was a quality answer ("improve satisfaction") rather than a cost-reduction answer.


My session was the first in a series of three webinars we are doing jointly with JustSystems. The next two sessions will focus on the DITA Open Toolkit. Simon Bate, Senior Technical Consultant with Scriptorium, will deliver an overview of the Open Toolkit on August 26 and a session on troubleshooting and customizing the Open Toolkit on September 23. The webinars are free, but advance registration is required here. Hope to see you there.

Labels: change management, presentations, xmetal, xml

11:27 PM Permalink | |

 
Free books are gone
posted by Alan
We've given away all the copies of the Technical Writing 101 book. Thanks for all the responses.

We are happy the books are going to readers instead of the recycling facility!

Labels: book, technical writing

1:16 PM Permalink | |

 
Yet more free copies of Technical Writing 101 (first edition)
posted by Alan
As I mentioned in an update to my post yesterday, we located more copies of the first edition of Technical Writing 101. We have divided this lot into four batches, each of which has nine or ten books. If you'd like one of these batches, please contact me at books@scriptorium.com. We will ship the books to you at no charge.

Update: We have given all the books away. Thanks for your quick responses!

Labels: book, technical writing

9:14 AM Permalink | |

 
Free copies of Technical Writing 101 (first edition)
posted by Alan
We have 27 copies of the first edition of our Technical Writing 101 book. We are no longer selling that edition, so we are giving away our remaining inventory.

To keep things simple, we have divided the books into three batches, each of which has nine books. If you'd like one of these batches, please contact me at books@scriptorium.com. We will ship the nine books to you at no charge.

Update: We have shipped all three batches. However, we think there are more copies lurking about. Stay tuned...

Labels: book, technical writing

8:26 AM Permalink | |

 
Is this the kind of advice we should give new tech writers?
posted by Alan
A recent blog post on getting that first job as a technical writer focuses quite a bit on desktop publishing tasks:

For example, I always had an aptitude for graphics, page layout, font selection, and spatial organization. I always had fun playing around with different imaging programs like Photoshop and Illustrator, or page layout programs like PageMaker.

Yet I never thought about those skills within the framework of technical writing. Back then I wasn’t even aware that more than half of the time spent on a typical technical writing project does not involve actual writing but organizing and formatting information in two-dimensional work-space.

I do not dispute having skills in different layout and illustration programs is a plus for a new tech writer. However, "organizing and formatting information" doesn't (and shouldn't!) take more than half of a project's time, particularly in today's smaller documentation departments with limited resources and tight budgets.

Taking time to figure out organization is essential, but spending a lot of time on formatting is a luxury and often unnecessary--especially in structured authoring workflows in which authors handle few (if any) formatting tasks. Even if you're working in an unstructured environment, a good template can automate formatting tasks so you can focus on getting the content right (which is a lot more important than getting it pretty, IMHO).

The blog post also doesn't take into account that a lot of content is single sourced these days: print, PDF, and many flavors of online help come from one set of files. Good tools can automate almost every aspect of the conversion processes for the various outputs, so there is no need to spend time formatting content.

In summary: having skills in all sorts of layout programs and illustration packages is helpful for a new tech writer. Having a basic understanding of how structured authoring solutions (including DITA) work is just as important--or even more so--for the next crop of technical writers. The days of desktop publishing for just print documentation are in the past.

Labels: technical writing

11:05 AM Permalink | |

 
Can this relationship be saved?
posted by Terry
For 15 years, I was a lovesick FrameMaker groupie. Ask anybody. As a founding member of the North Carolina FrameMaker Users Network (NC-FUN), I went to meetings regularly for ten years to talk about everything FrameMaker: plug-ins, database connectivity, scripting, single-sourcing, structure, obscure features, you name it. I couldn't get enough. FrameMaker was the great desktop publishing love of my life. When I joined Scriptorium Publishing earlier this year, I was given the task of updating Publishing Essentials: Unstructured FrameMaker 8. Yes! FrameMaker and I were inseparable.

But then FrameMaker 8 absolutely refused to produce an acceptable PDF file.

Whatever anybody might say about FrameMaker, one thing was always true: FrameMaker produced top-of-the-line PDF files. If you needed good PDF files, you included FrameMaker in your workflow. Now, PDF files produced from FrameMaker were a mess. Sure, some PDF problems had cropped up with earlier versions (and what relationship doesn't have a few PDF problems?), but it was worse now. Much worse. Undeterred, I tried a lot of things. I found some workarounds, but the problem was never really fixed. I could get text and high-quality pictures or I could have hypertext links, but not both. I felt angry and betrayed.

Pfft. Why not dump FrameMaker completely and just move my content to a dedicated XML editor? After all, XSL-FO could also give me a lot of trouble followed by lousy PDF output. I was this close to telling FrameMaker to hit the bricks.

Then Microsoft released a hotfix that patches the problems with Windows that are apparently the root of FrameMaker's PDF problems. So it's not all FrameMaker's fault after all. I applied the hotfix and FrameMaker is back in the house...

...but sleeping on the couch. I'm still miffed about the new conditional expressions. That's a post for another day.

You have to request the hotfix to get it: http://support.microsoft.com/?id=952909.

Labels: cranky, FrameMaker, humor

2:34 PM Permalink | |

 
Interesting times...
posted by Sarah
First, some bad news. I have decided to postpone release of our structured FrameMaker title. This decision was due to several factors, including the following:

• Disappointing sales of the unstructured FrameMaker 8 book. Frankly, based on the level of interest shown before the book was released, we expected a lot more sales at this point.
• Resource allocation. I need the people who were working on the book to focus on client projects. I suppose this is a good problem to have.
• Historically, FrameMaker has been on an 18-24 month release cycle. We're about a year into FrameMaker 8 already, which means we're looking at a lifespan of 6-12 months for this next book. And that's if we made it available TODAY. And the content is not ready.

We have a similar problem with our FrameMaker training workbooks. Our original plan was to update the unstructured book content, then the structured book, and then tackle the workbooks. Thus far, we haven't touched the workbooks to make the needed version 8 updates.

So we've decided to try something different, and that brings us to what I hope is the good news part of this post.

Today, we are launching wiki.scriptorium.com. Our new wiki currently includes the training content from our FM 101 (unstructured/accelerated introduction) and FM 201 (structured/introduction to authoring). We will also add the content of our other three FrameMaker workbooks as soon as possible. Our workbook content is for FrameMaker version 7, which means that about 90 percent of it is accurate for version 8.

As of today, you have access to free FrameMaker tutorial content. The sample files needed to complete the exercises are included on the wiki. Furthermore, we have licensed the content under a Creative Commons license, which means that you can reuse and repurpose the content as long as you provide attribution.

We hope that you will consider registering on the wiki and contributing to the needed updates.

Meanwhile, we will continue to offer live, web-based training on FrameMaker. You can also purchase PDF and printed versions of the workbooks from our store. The commercial versions have much nicer formatting than the wiki content does. For more details about the difference between the commercial and the wiki versions, see the front page of the wiki.

I know that some of you have been looking forward to getting the structured FrameMaker book, and I apologize to you for this change in plans. I hope that you'll find the wiki option a worthwhile substitute for the time being.

We are also looking at releasing some of the structured content (especially the DITA-specific information) as a stand-alone technical brief, but I don't want to commit to that approach at this point.

Labels: business, FrameMaker

3:10 PM Permalink | |