Building similar but different documents with databases, XML, VBA??

[kleefaj]

Greetings.

Does anyone have any ideas to share on how to manage multiple manuals
that are mostly very similar but different enough to warrant some kind
of target/source relationship?

I started my first official gig as a Technical Writer about a month
ago. The main reason I was brought on board was to make it easier to
update and maintain the large (to me, 48 manuals is plenty) number of
manuals the company distributes with their products. Manuals are
composed in Microsoft Office Word 2003 Standard and distributed as PDF
files.

There are four main products across three platforms using four (soon
five) different versions of hardware. But the applications across
platforms and hardware are very similar. In fact, across hardware
version versions they're exactly the same: the driver installations are
different.

What I've been doing is introducing formatting standards (via styles)
just to get the manuals to look the same. Then I've been comparing
documents, trying to figure out exactly what elements (that is,
sections) are the same or almost the same across manuals.

I thought I'd eventually make use of Word features like Bookmarks and
IncludeText fields but issues with relative paths turn me off to this
idea. I think making use of a database to build documents would be
useful. It would also prove useful when I need to make one change to
eight manuals, somehow getting around the idea that I'd have to do the
updates eight separate times.

An associate of mine suggested that the capabilities of XML would serve
my purpose very nicely. I'm guessing that with XML, some code, and a
database I could put together quite the solution. Or I may be
overengineering the problem altogether.

Thanks for your attention. I'll update this thread as more ideas,
questions, and conclusions come my way.

-Jeff

 

[Cindy M.]

Hi (e-mail address removed),

I thought I'd eventually make use of Word features like Bookmarks and
IncludeText fields but issues with relative paths turn me off to this
idea. I think making use of a database to build documents would be
useful. It would also prove useful when I need to make one change to
eight manuals, somehow getting around the idea that I'd have to do the
updates eight separate times.

An associate of mine suggested that the capabilities of XML would serve
my purpose very nicely. I'm guessing that with XML, some code, and a
database I could put together quite the solution. Or I may be
overengineering the problem altogether.

Can you elaborate on the difficulties with IncludeText? That was the
first thing that occurred to me, as I was reading your problem
description...

For the database approach you'd need to do some programming, so you'd
want to pursue that (if you decide to go that way) in a different
newsgroup (word.vba.general, for example).

The XML approach would require creating a transform (xslt) and possibly
a schema (xsd), which can be a lot of work, but in the end you wouldn't
need much (if anything) in the way of programming code.

Cindy Meister
INTER-Solutions, Switzerland
http://homepage.swissonline.ch/cindymeister (last update Jun 17 2005)
http://www.word.mvps.org

This reply is posted in the Newsgroup; please post any follow question or
reply in the newsgroup and not by e-mail

 

[kleefaj]

Hi (e-mail address removed),

Can you elaborate on the difficulties with IncludeText? That was the
first thing that occurred to me, as I was reading your problem
description...

I understand that IncludeText relies on absolute paths. More
specifically, the behavior of how Word looks for files that are listed
in the IncludeText field is too brittle to be reliable. Putting all my
"included" files into one bucket (read: directory) isn't a viable
solution for me.

-Jeff

 

[Cindy M.]

Hi (e-mail address removed),

I understand that IncludeText relies on absolute paths. More
specifically, the behavior of how Word looks for files that are listed
in the IncludeText field is too brittle to be reliable. Putting all my
"included" files into one bucket (read: directory) isn't a viable
solution for me.

No, IncludeText supports both absolute as well as relative paths. But if
you don't all the files in "one bucket" you'd prefer absolute paths,
wouldn't you?

The biggest danger would be the "Update links automatically on save" in
Tools/Options/General/Web options/Data, as that has a nasty tendency to
change a file path if it's in a directory relative to where the document
is saved. However, you could put a macro in the document that makes sure
this is turned off before allowing the document to be saved...

Cindy Meister
INTER-Solutions, Switzerland
http://homepage.swissonline.ch/cindymeister (last update Jun 17 2005)
http://www.word.mvps.org

This reply is posted in the Newsgroup; please post any follow question
or reply in the newsgroup and not by e-mail

 

[kleefaj]

Hi (e-mail address removed),

No, IncludeText supports both absolute as well as relative paths. But if
you don't all the files in "one bucket" you'd prefer absolute paths,
wouldn't you?

Cindy,

I'd like to keep a "working" IncludeText directory tree on my
workstation and a "production" IncludeText directory on the network
server. I'd make updates and changes to the working directory and then
copy them to the network server. Once a document is ready for
production and I move it to the network server, the link to the
original working IncludeText file will be broken by using an absolute
path to my local workstation. I'd prefer to keep the linked material on
the network server.

I experimented with using a relative path in an IncludeText field but
Word complained: "Error! Not a valid file name." Here's the path:

"\\Production\\Users Manuals\\WORD DOC VERSION\\The Document.doc"

Any thoughts?

Thanks,
Jeff

 

[kleefaj]

Cindy,

Just came across your article, "How to Use IncludeText Fields". I'll
take a look through there and see what I can come up.

Thanks,
Jeff

 

[kleefaj]

Cindy,

Just came across your article, "How to Use IncludeText Fields". I'll
take a look through there and see what I can come up with.

Thanks,
Jeff

 

[Cindy M.]

Hi (e-mail address removed),

I'd like to keep a "working" IncludeText directory tree on my
workstation and a "production" IncludeText directory on the network
server. I'd make updates and changes to the working directory and then
copy them to the network server. Once a document is ready for
production and I move it to the network server, the link to the
original working IncludeText file will be broken by using an absolute
path to my local workstation. I'd prefer to keep the linked material on
the network server.

I experimented with using a relative path in an IncludeText field but
Word complained: "Error! Not a valid file name." Here's the path:

"\\Production\\Users Manuals\\WORD DOC VERSION\\The Document.doc"

The path you show would require a dot or two (depending on the
relationship) before the first \\

Another possibility - and probably the path I'd choose - would be to
store the base path in a document property (File/Properties) or a
document variable (can only be accessed using VBA). Just before you
"publish" the document, change the path to reference the server. An
example:

I create a custom property named LinkPath and assign it the string value
(yes, single backslashes): C:\my project\working folder\

In the document, I display all the field codes (Alt+F9) then go to each
IncludeText field, delete the path and put in its place: { DocProperty
LinkPath }

Then Alt+F9, Ctrl+A, F9 to hide the field codes then force an update of
all the fields. If no error messages appear, everything is OK.

Now, when I want to put the file on the server, I just change the path in
the custom document property, load the document to the server, open it
and Ctrl+A, F9 to force the links to update.

Note that this could also be done with an AutoOpen macro. The macro could
even dynamically get the path information and write it to the property
(or variable).

Cindy Meister
INTER-Solutions, Switzerland
http://homepage.swissonline.ch/cindymeister (last update Jun 17 2005)
http://www.word.mvps.org

This reply is posted in the Newsgroup; please post any follow question or
reply in the newsgroup and not by e-mail

 

[kleefaj]

Another possibility - and probably the path I'd choose - would be to
store the base path in a document property (File/Properties) or a
document variable (can only be accessed using VBA). Just before you
"publish" the document, change the path to reference the server. An
example:

I create a custom property named LinkPath and assign it the string value
(yes, single backslashes): C:\my project\working folder\

Cindy,

I experimented with this using your "How to Use IncludeText Fields"
article and it worked perfectly! I was also able to extract the
LinkFilePath value from the document using a Perl script so I now know
how I can programmatically get and set the value.

I like the idea of using the AutoOpen macro for setting the path. It'd
be something along the lines of, "Set LinkFilePath equal to wherever
I'm located," and make sure I have the IncludeText directory in the
same path. Or something like that. :-D

Thanks for your help!!

-Jeff