TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Avoiding mainenance nightmares (was Brainstorming request) From:Gwen Thomas <thomasgp -at- CBS -dot- FISERV -dot- COM> Date:Thu, 18 Feb 1999 11:41:30 -0500
Request for information:
Has anyone out there used PatternStream? It's a FrameMaker database publishing application from Finite Matters. Would love to hear from you. Context at end of this (long) post. Gwen
Julie Tholen had a Brainstorming request:
folks who have taken a legacy book and craved it up into a new format. I have a reference guide that needs to have its procedures used in another book that will be delivered as an HTML.
I use FM and then WWP for the HTML conversion and that has worked well. But I think that I am getting into a large maintenance nightmare. I want to do this as a single source project, but I don't know if that is realistic or not.
Whether it's realistic or cost-effective to produce true single-source for this project depends on the content of the legacy doc. Is it comprised of repetitive units? If so, then this information may be a candidate for migration to a document database. Using the database approach, you would maintain the project contents (data, information) in a database (choosing the appropriate application: database application, word processing tables, spreadsheet). Then you'd use templates, etc. to generate out BOTH a "reconstructed" legacy book and any new projects.
Using this approach, you only maintain content in one place. And that content is available to an infinite number of end products. The database approach is fundamentally different from doc approaches where you write one set of information and try to use formatting or selective text to fashion new doc serving a new purposes. In such a case, it's easy to get yourself into a situation where your "single-source" has text that simply doesn't belong in the new end product - or doesn't belong there in the order of the original - and you don't know how to deal with it.
Instead, using the database approach, constructing a new end-product is like ordering from a Chinese menu: I'll take X from Column 1, A, B, and D from Column 2, and nothing from Column 3. You can put these elements in any order, using any format. You can even use conditional text ("Use this program to" + Program_Purpose in one end-product, "Program Purpose: "+ Program_Purpose in another end-product, etc.)
Even if you find that you need two presentations (versions) of the same information, this approach makes that easier than traditional approaches. (For instance, you might need both reference-based field descriptions and imperatives.) Copy the column with the original info into a new column. Then make whatever revisions are needed. Now you have 2 versions available, but you haven't doubled your work, because both versions probably share a lot of other information you haven't had to touch. You'll be less likely to forget to maintain one version, since it will be sitting in front of you when you maintain the other.
Note: You want to avoid a maintenance nightmare. But you also have to be careful to not put more time into a project than it is worth. However, this approach does NOT require an "all or nothing" work practices decision. You do not have to throw out the legacy doc and start over. You could, for instance, just pull out a section, maintain it using the database approach, and pop the formatted results back into the legacy doc when done.
I'm taking this "slow migration" approach for a technical manual I'm currently updating for a client. Lots of new data, and the client also wants new formatting. Not sure what that should be, but they'll know it when they see it. Oh, and they're about to start thinking about offering help, so I'm to keep that in mind. (It's a fantastic client. Not flighty, just in transition mode.) The client needs Word files as the end product and absolutely does not want to buy a database program for all of the writers at this time. Previous practice had been to copy the files from the last release and add/maintain information. However, maintaining the technical listings for the last release of this manual did not go easily (one reason the consultant was now consulted?). My solution: I've pulled out the data, put it in a series of Word tables, one table per document, and am in the process of updating the information. Not a true database, but it works. The time invested in "mining" the data is paid back by shorter update times. Then I'll present prototypes. Tweaking templates is easy, so it will be easy to be patient as the client decides on formats. I generate sections using Word Mailmerge catalog functionality, paste the sections into the Word files, and this release is done. If the doc manager wants to throw away the "database" he can. However, an in-house writer will probably be doing the next update, and so far the group is inclined toward keeping the content files and adopting this approach.
I've used this approach successfully for many projects over the past few years. However, never for a Frame project. So, I repeat earlier inquiry. Has anyone out there used PatternStream or any other product
that works with Frame?
e-mail Gwen_Thomas -at- yahoo -dot- com