departing from a template

[Ellen Vanrenen]

We have a style guide and a template. Our manager, who is the manager of Customer Service and Support, becomes unhappy when we depart from the template. I created the template. It is mostly for end user documentation, and I always envisioned it as the "core" from which individual documents might vary to some degree, depending on the needs of the writer. With some variation allowed, documents would still have the same "look and feel" if the writer adhered to the fonts and so forth.
Is it usual to consider a template the only way to create documents of the same type, allowing the documentor no freedom depending on the individual document?

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Free copy of ARTS PDF Tools when you register for the PDF
Conference by April 30. Leading-Edge Practices for Enterprise
& Government, June 3-5, Bethesda,MD. www.PDFConference.com

Are you using Doc-to-Help or ForeHelp? Switch to RoboHelp for Word for $249
or to RoboHelp Office for only $499. Get the PC Magazine five-star rated
Help authoring tool for less! Go to http://www.ehelp.com/techwr

---
You are currently subscribed to techwr-l as: tech...@GTS.ORG
To unsubscribe send a blank email to leave-tech...@lists.raycomm.com
Send administrative questions to ej...@raycomm.com. Visit
http://www.raycomm.com/techwhirl/ for more resources and info.

[David Knopf]

Ellen Vanrenen wrote:

| We have a style guide and a template. Our manager, who is the manager
of
| Customer Service and Support, becomes unhappy when we depart from the
| template. I created the template. It is mostly for end user
documentation,
| and I always envisioned it as the "core" from which individual
documents
| might vary to some degree, depending on the needs of the writer. With
some
| variation allowed, documents would still have the same "look and feel"
if
| the writer adhered to the fonts and so forth.
| Is it usual to consider a template the only way to create documents of
the
| same type, allowing the documentor no freedom depending on the
individual
| document?

This varies from shop to shop, so I can't say that it's "usual." But it
is certainly the best practice. Our writers are not allowed to create,
modify, or override styles defined in the templates we use.

Regards,

David Knopf / Knopf Online / San Francisco, CA / 415.550.8367
mailto:da...@knopf.com / http://www.knopf.com

WebWorks and RoboHelp Certified - RoboHelp MVP
Member, JavaHelp 2.0 Expert Group
Moderator, HATT & wwp-users

[David Brown]

Ellen Vanrenen wrote:
|
| Is it usual to consider a template the only way to create documents
| of the same type, allowing the documentor no freedom depending on the
| individual document?

I don't know about the rest of the list, but I couldn't work under such an inflexible constraint.

Different books inevitably have "special needs" that aren't addressed in a department-wide template. If you incorporate every minor variation of every paragraph style in a single template, the style list quickly becomes unusable (I suffered through that for several years at a former job, where there were around a hundred paragraph styles, including dozens of variations for body text--agh!--never again). At the other end of the spectrum, you'd need a different template for each document, which defeats the purpose of the template.

Given a consistent style across documents (which the existing template gives you), internal consistency is more important in the handling of any special cases that arise.

I don't recommend, however, that variances be introduced simply to satisfy the artistic whim of the writer--they should address legitimate needs of the document.

--David

========================================================================

N O W A V A I L A B L E ! http://www.html-indexer.com/

HTML Indexer 4 is still the easiest way to create and maintain indexes
for web sites, intranets, HTML Help, JavaHelp, and other HTML documents.

Now with fully integrated cross-references, target frames and windows,
multiple-file output, "one-step accept" of default entries, and more!

[Sarah Kampman]

| Is it usual to consider a template the only way to create
| documents of the same type, allowing the documentor no freedom
| depending on the individual document?

In my experience, the template is Not To Be Overridden. But it depends on
why the template was created, and what you're doing with the documents
created with it. The following are some organizations' common reasons why
the template shouldn't be changed/ignored/overridden:

* Templates ensure consistent use & naming of styles. This is critical if
your organization moves documents from format to format (e.g., Word->Frame,
Frame->HTML, etc.)...overridden or new styles work strangely or not at all.

* Templates help curb writers' urge to be creative with layout, which can be
a good thing if the writers are no design geniuses. This is important if the
docs are going public with a minimum of editing or desktop publishing.

* Templates help flatten the learning curve between authors and revisions.
If a document will be updated frequently, especially by one or more writers,
using the template consistently will prevent those stunned moments of "how
the heck did they get it to do that?"

* Templates move the writers' focus away from design and back to content. A
strict standard can save your organization hours of font-f0ndling time, if
the writers would otherwise be so inclined.

* Templates make the docs look consistent. This is particularly nice when
users will frequently be jumping from document to document, such as in a
knowledge base...having the docs all look the same prevents confusion &
looks more professional.

If these aren't concerns for your organization -- and more importantly,
won't be for the forseeable future (re-applying templates and fixing
problems across every doc is not fun) -- then by all means, change away.
:-)

Hope that helps,
-Sarah

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

[Ed Gregory]

I heard a wise consultant say once that, no matter how bad it looks to you,
somebody is as proud of that template or source material or procedure as a
new parent would be of a mug-ugly infant.

So what do you say in those situations?

"My, what a beautiful baby you have."

Then, after a respectful time has passed while, you can help with makeup
tips.

If there is a helpful-but-incomplete template and you are in a position
(opportunity and authority) to change some of the styles used and
definitions for those styles, then:
1. Create a copy of the template.
2. Save it for your document/purpose under a different name.
3. Play with your copy.
4. Make it clear up front to all stakeholders that your document uses a
different template from the norm, or than it came with.

And, most of all, good luck!

-Ed Gregory

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

[Martha J Davidson]

At 01:47 PM 4/16/2002 -0600, Ellen Vanrenen wrote:
|We have a style guide and a template. Our manager, who is the manager of
|Customer Service and Support, becomes unhappy when we depart from the
|template. I created the template. It is mostly for end user documentation,
|and I always envisioned it as the "core"

...

|Is it usual to consider a template the only way to create documents of the
|same type, allowing the documentor no freedom depending on the individual
|document?

I think it depends on what you mean by "template" here. If you are
referring to the collection of acceptable formats (page layouts; paragraph
and character styles; table formats; etc.), then I agree with your
manager. If you discover that the universe of available formats does not
cover all of the circumstances you encounter, then maybe it's time to
extend the template.

If, however, you mean a standard framework or outline that you use
to address the topics you are documenting, then I agree with you.
It's always helpful to start with a basic structure that covers the
main topics you are likely to cover as you document different aspects
of a system, but no structure can accommodate all of the topics
you are likely to need to address. If this is the case, then your
manager's perspective sounds limited to me. If, as you say, your
template forms the "core" of what a document needs, then I would
consider it a starting point, not an absolute format for any and all
documents.

martha

--
Martha Jane {Kolman | Davidson}
Dances With Words
mailto:edi...@nemasys.com

"We must become the change we want to see in the world."
--Gandhi

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

[Annamaria Profit]

Ellen,I don't know about IT, but it sure is in corporate America. All
company documents, including letters, faxes, memos, manuals, promotional
materials, marketing brochures, etc--everything! (Although I've rarely seen
company logos on the Scott tissue! ; )))

At 01:47 PM 4/16/02 -0600, Ellen Vanrenen wrote:

|We have a style guide and a template. Our manager, who is the manager of
|Customer Service and Support, becomes unhappy when we depart from the
|template. I created the template. It is mostly for end user documentation,

|and I always envisioned it as the "core" from which individual documents
|might vary to some degree, depending on the needs of the writer. With some
|variation allowed, documents would still have the same "look and feel" if
|the writer adhered to the fonts and so forth.

|Is it usual to consider a template the only way to create documents of the
|same type, allowing the documentor no freedom depending on the individual
|document?

Annamaria Profit
E-mail: inte...@earthlink.net
URL: http://home.earthlink.net/~inteltek2
"Where it is possible, live in peace with all men."
(Romans 12:18)

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

[Carey Jennifer (Cry)]

Hi Ellen,

I have to use a style guide and template where I work too. I break rules all
the time but i try to keep them small. My understanding is that certain
departures from the template can cause problems down the road when it comes
time to upload the documents (through another application) so that they can
be viewed remotely by employees all over the world. But, never having been
through the process of uploading myself I don't know exactly what the
dynamics of it all are (I will soon though, heaven help me).

If it's just a "look & feel" issue, inflexibility on minor variations seems
arbitrarily precise (especially when it was you that defined the template to
begin with). Despite the potential problems associated with departing from
our template, the folks who mandated / designed this in the first place (who
are Swiss and notoriously rigorous when it comes to rules) expect that each
writer may find cause to vary from the standard a bit.

What they did was to define exactly what fell into the catagory of
"required, not negotiable", and everything else is a recommendation but can
be changed. That has worked really well so far and I love the template
(since it saves tons of mind-numbing formatting time), but I'm still allowed
the freedom to make decisions and changes where i think it's appropriate.

My advice: discuss discuss discuss.

Good luck!
Jennfer
-------------------------------------------
Ellen wrote:

We have a style guide and a template. Our manager, who is the manager of
Customer Service and Support, becomes unhappy when we depart from the
template. I created the template. It is mostly for end user documentation,
and I always envisioned it as the "core" from which individual documents
might vary to some degree, depending on the needs of the writer. With some
variation allowed, documents would still have the same "look and feel" if
the writer adhered to the fonts and so forth.
Is it usual to consider a template the only way to create documents of the
same type, allowing the documentor no freedom depending on the individual
document?

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

[johanne....@locusdialog.com]

Ellen wrote "....Is it usual to consider a template the only way to create

documents of the same type, allowing the documentor no freedom depending on
the individual document?"

As others have pointed it, it really depends on what the template is for,
and what kind of overrides you are talking about.

I would add that templates are a great way to enable people outside the
documentation department to be responsible for their own documents while
respecting documentation guidelines and standards. For example, we've
worked hard to establish to come up with a certain look and feel for our
technical documents. We've gotten great feedback on how easy they are to
use, clearly written, well-organized, etc. So we came up with some
templates for other departments to use; we provide the form, and they just
plug the content in. That way, those docs have the documentation seal of
approval, if you like, but we aren't responsible for them.

If that's the kind of thing you're after, then no, writers shouldn't stray
from the templates. However, if the templates were set up more as
guidelines, then it's up to you to decide how flexible they should be.

My two cents, hope it helps.

Johanne Cadorette

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

[Sean Hower]

Templates are good, IMHO.

|From experience, departing from the template, in certain situations, can be a mess. For example, I've had to clean up RoboHelp projects where the creator had simply used the Normal style throughout the document, changing paragraph and font settings as needed. (I still don't understand why they did that. If I think too hard about it, my head implodes.) That's an extreme example, but I've also had to clean up minor things that were kind of hard to track down, like variances in paragraph spacing that made the document look wrong but we couldn't quite put our finger on what it was.

IMHO, templates and structure shouldn't be messed with unless there is a really good reason to do it (we have to occasionally depart from our help format to accomodate unforfeen issues.) It just goes for consistency, which users come to rely on. However, I think writers should be allowed some creativity with the content as long as it meets standards of quality.

********************************************
Sean Hower

technical writer
http://hokum.freehomepage.com

_____________________________________________________________
Create your own web site for FREE at http://www.freehomepage.com

_____________________________________________________________
Run a small business? Then you need professional email like y...@yourbiz.com from Everyone.net http://www.everyone.net?tag

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

[Sue Ahrenhold]

|>We have a style guide and a template. Our manager, who is the manager of
Customer Service and Support, becomes
|>unhappy when we depart from the template. I created the template. It is
mostly for end user documentation, and I
|>always envisioned it as the "core" from which individual documents might
vary to some degree, depending on the
|>needs of the writer. With some variation allowed, documents would still
have the same "look and feel" if the
|> writer adhered to the fonts and so forth.

|>Is it usual to consider a template the only way to create documents of the
same type, allowing the documentor no
|>freedom depending on the individual document?

I think it's becoming clear that the your original concept of the document
seems to be more book- and writer-centric than perhaps the manager's was.
If the materials are going to be "re-purposed" (amazing how our day's topics
have coalesced) it is likely that there will be a lot of macros that change
fonts and spacing to make the material reusable.
Real simple example: Say that a writer writes a document, adjusting the
predefined spacing by adding 2 points between lines. Then a sales manager
wants to take a section of that document and put it into a PowerPoint slide
show -- something he has done before. But, because of the custom spacing,
he has to change his formatting to take out the extra spacing. He is going
to complain to your manager that "you guys are changing your templates."
This is an overly-simple explanation -- where you are going to have problems
is when the books are put into help files, or onto web applications.
Shops where information is re-used in lots of outputs are real
template-Nazis for this reason.

[Janice Gelb]

In article A49A7712BBF66B42901...@COCPISEX1.clear-technology.com, ellen.v...@clear-technology.com ("Ellen Vanrenen") writes:
|
|We have a style guide and a template. Our manager, who is the manager of =
|Customer Service and Support, becomes unhappy when we depart from the =
|template. I created the template. It is mostly for end user =
|documentation, and I always envisioned it as the "core" from which =
|individual documents might vary to some degree, depending on the needs =
|of the writer. With some variation allowed, documents would still have =
|the same "look and feel" if the writer adhered to the fonts and so =
|forth.
|Is it usual to consider a template the only way to create documents of =
|the same type, allowing the documentor no freedom depending on the =
|individual document?
|

I think the key phrase here is "documents of the same type."
A good template should be flexible enough for everyone to
be able to use it to create documents of a similar type.
As you note, creating a common look and feel is important,
so you don't want individual writers to have blanket permission
to deviate either. One person's slight variation is another
person's completely different look and feel.

If you have documents that are so different that the template
does not work for them, you may need to have different templates
for different needs. For example, we have different templates
for white papers than for user documentation.

*********************************************************************
Janice Gelb | Just speaking for me, not Sun.
janic...@eng.sun.com | http://www.geocities.com/Area51/8018/

[Bruce Byfield]

Martha J Davidson wrote:

|
|
| If, however, you mean a standard framework or outline that you use
| to address the topics you are documenting, then I agree with you.
| It's always helpful to start with a basic structure that covers the
| main topics you are likely to cover as you document different aspects
| of a system, but no structure can accommodate all of the topics
| you are likely to need to address.
|

A good illustration of this point: a very large company (that will
remain anonymous) spent a good chunk of money buying such a framework
from a consultant firm. I've gone through much of the resulting
documentation, and the quality ranges from poor to completely
inadequate. So far as I can infer, people felt that, so long as they had
put something under each heading, then they had done their job. Their
managers signed off in the same spirit, and the resulting documents were
carefully stored on the servers,where they occupy gigabytes of space,
are never used, and are becoming obsolete. Just as before the great
documentation effort, anyone who needs concrete information in the
company sidles over to the handful of knowledgable people in the
company, or sift through old e-mails and folders of saved snippets of
information. Out of several hundred documents,only three or four - all
written by the same person - were complete enough that I could actually
use them to go through a process.

I'm not saying that outlining has no purpose. Obviously, it does.
However, keeping too closely to such a framework can be as inefficient
as plunging into a documentation project with no planning at all. In
fact, in some ways, it may be worse. Some people can work quite well
without a plan, and, even those who can't at least have a chance of
seeing some sort of order as they stumble along. Without a plan, writers
may be inefficient, but they might still manage to produce documentation
that's useful. However, as in the company mentioned aboved, it's
perfectly possible to complete a rigid outline and never notice that the
result wasn't worth the effort.

--
Bruce Byfield 604.421.7177 bbyf...@axionet.com

"Never eat at a diner called 'Mom's,' never play cards with a guy named 'Doc,' and never get involved with a woman who's got bigger troubles than you."
- Nelson Algren, The Man with the Golden Arm