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:RE: Looking for re-packaging publishing app From:Paul Hanson <PHanson -at- Quintrex -dot- com> To:techwr-l -at- lists -dot- techwr-l -dot- com Date:Tue, 9 May 2006 08:01:14 -0500
>From my perspective, I don't think it's "reaching a bit" at all.
Here's how I look at it.
The files I use to create my distributed files, whether it be in MS Word,
Dreamweaver, Paint Shop Pro - whatever tool I happen to be using - is source
code. Thse files are manipulated to create an output. There is only one way
to have content/changes made to my source files. I make the change in MS
Word, DW, PSP - whatever. Then I distribute it.
For users, there are two ways they can customize the content.
1) Submit a request to me to change the text. This changes the source code
and is my job.
2) Annotate the output, such as a link to a Word doc or some other file
format that the end-user can customize. This does not change the source
code.
As background, I distribute both compiled help files and uncompiled help in
a browser format. There are specific rules that have to be followed to make
these formats work. For example, when I am editing HTML code, I must have a
closing tag. That is what I am referring to when I say "the rules" below.
Someone that does not know "the rules" is not qualified to make changes to
the documentation source files. Period. In the same breath, I know that I am
not qualified to make changes to any programming code. I don't know "the
rules" of creating the output. For programmers, it's an .exe file or some
other interaction with the user. For me, it's my CHM or HLP or WebHelp
files. I'm reminded of an incident at my first TWing job. I needed to find
the valid values for a field and was directed to go talk to the programmer.
He opened up the source code for the program and showed me how to search the
source code for the field name. I took notes for how to do this and went
back to my desk. As I was working on finding the valid values, my mentor
came by. "What are you doing in the source code?!?" she demanded. "The
programmer told me how to go in and find the valid values." The steam poured
out of her ears. "You never, ever, go into their source code." The message
was, "You don't know how to program so you don't know "the rules" for being
in the source code." Ten years later, I think that still rings true. I
wasn't scarred from this experience, but it taught me to stay out of the
source code.
Another issue I think about is how I have read complaints on this list (and
other lists) running along the lines of "The previous writer left me a mess.
I have a Word doc that is formatted in Normal style with manual formatting.
Now I have to clean up this mess." If someone wants to mark up an existing
document, that's fantastic. Go for it. That's marking up the output of what
has been created. I do the same thing. I put yellow Post-It notes all over
and highlight sections of the documentation that are importatnt. I have it
set up to allow our users to annotate our files. I think these are fantastic
ways for users to customize the documentation we write.
But in both annotating a help file with custom content and marking pages of
a printed manual, it is customizing the "output" of the source files. What I
think the original post was talking about was customizing the "input"
(source files) to get a desired document. That is where I envision that I'd
want to be careful in this situation. Someone who doesn't know the rules
could be making up their own rules. The possibility of the company
distributing incorrect information is present. What if comes back on the
original document writer?
In my mind, a better strategy is to work with the person who wants the
customized content to potentially set up the source files to allow what they
want easier. However, there is a cost involved in setting this up and at
that point, deferring to a manager is the course of action I would follow to
make that decision.
Let me be clear:
I am not opposed to customized help.
I am not opposed to helping someone get the cusomized content they want in
the format they want it in.
I am opposed to the source document being customized by someone that doesn't
know "the rules" that must be followed.
Another example I thought of is what would be the reaction if "you" (not
Gene specifically, but you in the general sense) didn't know how to program
in your programming language and you called over the cubicle wall, "Hey
Mark, can you tell me where I can get a copy of your source code for the
apples.exe app. I want to customize it." Would that go over where you work?
It wouldn't here and that's the perspective I was trying to get across when
I responded earlier.
<snip>
but customers and field service people adding case-specific notes to
documents was a common occurrence back in the days when manuals were
delivered in 3-ring binders, and is a capability that has been largely lost
in today's electronic documents.
<snip>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today!. http://www.webworks.com/techwr-l
