DEADLINES summ. Part 3
beth_staats -at- ARTISOFT -dot- COM
Wed, 26 Jun 1996 11:33:55 MTN
THIS IS THE THIRD PART of the message titled: DEADLINES summary
If your company goal is to produce a quality product with quality
documentation rightfully a part of that product, then your 3-week deadline
is very out of step. Where I work, we send the manual to the printer the
day the software is considered delivered. [I should probably also tell you
that our print runs are short, fewer than 5,000, and black and white, so we
don't need a lot of time.] If necessary for the sake of a quality manual,
we would slip the printing date.
Your take on Readmes is absolutely correct. They may have a role in
software that is by nature rush rush and last minute (income tax software,
for example, or maybe the software of a precocious but disorganized
graduate student) but they are out of sync with the output of a large,
well-organized, professional, business-like, detail-oriented corporation
concerned about its image. Do your corporate executives (the males among
them) wear white socks with their blue suits?
If you haven't already heard from xxx, this will be news -- if you have,
then it will be reinforced.
When xxx and I worked together, our manager had a saying: "The doc clock
start until the UI is frozen." He would not guarantee dates until we had a
UI. I use this with my clients. I tell them up front that I can meet the
dates or I can make sure all the features are covered in the software. If
they expect software and do to be finished at the same time, I cannot
promise that all the features will be covered accurately.
Doing this has cut a lot of the stress. It's right in the contract so
there are no surprises or arguments.
I work in a unique situation where they can't legally ship product without
documentation (medical devices). Hence, they are careful to include us in
the beginning of the product development cycle. They also have to write a
design spec. before beginning the project.
However, they do try to make changes up until the last minute. I got
around it by writing the manual early based on the design spec and early
bash testing, then putting it through our review and sign-off processes.
Then, when they made technical changes, I would make the changes in the
manual and get those sections re-reviewed. That way, you aren't trying to
write the whole manual at the last minute. Also, because I'm involved
from the get-go, I provide the project manager with a timeline and
documentation plan, with time estimates and potential monkey wrenches
outlined. Most of the project managers have learned that freezing the
software before the manual has gone to print saves them $$. We also had
an on-site print shop that provided on-demand printing, which helped.
We face a very similar situation in our company. The deadline for our
docs is generally two weeks before the code is finalized. In theory, the
code is supposed to be 'feature frozen' at this point, but in actuality,
it isn't always.
We've had cases where our manuals go to the printer and then the product
date slips. This means the engineers continue to change the software. We
had one instance where an entire chapter was wrong, because after the
manual went to print, they had to pull out and radically change a feature.
Ugh! We were able to fix it in the localized versions of the manual, but
the English remained wrong.
Hee hee hee hee hee - how OLD are you, young lady?!!
Grizzled grunts know it's merely status quoed ("code", get it?)
I don't know if it's standard. It is NOT what I have here. On my first
project here I was given about 3 weeks *after* the freeze. This would have
been less time, granted, but they sneaked a few more changes in after the
so-called freeze, and every time there was a change, my manager said I
would need more time. Your company is asking you to do a job with your
hands tied, and it sounds like you suffer along with the quality of the end
Good luck - I hope you can use this response to point out the error of
IMHO, that's ludicrous. In bad situations, code and documentation must
deliver at once with only about two days for printing (quick print
situations). In good ones, the interface freezes two weeks before the
documentation must be ready and about four before the product releases.
That gives time to finish the docs and get them printed before ship date.
Developers will still be busy fixing bugs up to the ship date but keeping
them from tweaking the interface will allow you
to retain some sanity.
Thinking back to the various places I've worked, scheduling seems to go
something like this: start with first customer ship (the date docs have to
be in stock to ship to the customer), backup up six weeks (or whatever
amount of time the printer needs) and that's when you need to have your
docs done. sometimes this time varied depending on production issues
(perfect bind vs. binders, printer receives hard copy vs. electronic copy,
etc.). at one place, it took six weeks to print anything, no matter what.
maybe there are some production-type variables you can play with to give
yourself more development time. where i now work, we are able to get docs
back from the printer in less than a week. this is typically 50 copies of a
100 page document. we do plastic binding in-house. this allows us to
include all but the very latest changes, if any, in our docs.
the value tech pubs can add to a product by supplying complete and
accurate documentation is inestimable (oh no, xxx's getting on his soapbox
- he's using words he can't say or spell!) it's worth every effort to keep
document development as close as possible to product development.
The situation you cite is all too true, these days. Most of my situations
have involved a dictate to "synch with the code release date." At a few
companies, Development has had the discipline to institute a formal QA
process and a code freeze. These times are joys.
Most companies I've worked with don't have this level of planning and
procedure and result in the last-minute rushes you cite. The most common
mindset among upper managers these days is "get it to market faster." Like
most simplistic approaches, this one has repercussions that too many
corporations continue to ignore.
"Cheaper" and "faster" are the only objectives. And they wonder why
customers continue to be so difficult.
Your company has never been known to play by sensible rules. Your head of
Engineering is an example of this. [Editor's note: the person referred to
is long gone.]
Your company is a great example of an engineering-dominated company, rather
than a marketing-dominated company. In the former kind, the focus is on
getting the latest bells and whistles into a release. In the latter kind,
the focus is on what the customer gets, or perceives, and how he reacts to
the company as a result. A release with bugs in the software, inaccurate
manuals, and misinformed support lines reflects on the company, not on the
Engineering-dominated companies are a dime a dozen, and ultimately they
don't last, precisely because they care more about the product than they do
their customers. But as long as your company has that mentality, you as a
documentor can do little about it.
It is *not* standard in the industry for companies to keep changing the
software after the manuals are released. What may happen is that the
*interface* may freeze so that the manuals can get written, but the
underlying code can get modified a bit so long as it doesn't change the
interface. But in terms of changing the software in ways that affect the
docs/help systems/support material, Microsoft doesn't do it; Novell doesn't
do it; Cisco doesn't do it; Netscape doesn't do it; I could go on and on.
Over and over and over these companies' engineering departments have
learned that if the support material doesn't reflect the product, the
customer loses trust in the company. To think otherwise is typical of the
arrogance of a young, immature engineering mentality.
I've been in the computer business in Silicon Valley since 1968, and now
own a company that specializes in helping too-busy people learn how to use
complicated software tools. Sometimes we create the tools, too. We walk
away from the little engineering companies that keep thinking that docs
don't have to reflect the released software.
This seems to be a trend where I work also (at least concerning the
project I'm working on). We just launched the project and I was working
60+ hrs/wk for about the 3 weeks prior to my production deadline. We
never seem to get the code on time or when we need it. In my case, the
code is done in Virginia, and we (the documentation department) are in New
In fact, I just met with my manager and the other woman doing customer
training for the project I'm on; the topic was estimating our time
required for a release in August. They (the fools in VA) want to launch
(NOTE: Launch means our deadlines are ~2 weeks prior to the launch date.)
at the end of August, but they claim they can't get any code to us until
mid-July. Yet, they still expect me to pump out an updated and complete
200-page user guide (with numerous screen changes) in what--4 1/2 weeks???
It always seems that the code is never available, let alone frozen, within
a timeframe that would allow us to work at a somewhat normal pace.
So, in answer to your question (I apologize for the raving, but this
meeting just took place), it may not be the official SOP, but it does seem
to be the most common trend (and I wish it would stop).
P.S. In my case, I'm at least lucky enough to have a manager who
understands the time constraints we are put under and who tries his hardest
to get us the timeline we need for our documents. He really fights for us
and appreciates the miracles we are called upon to perform. I'm sure there
are others out there who aren't as lucky.
You have it worse than I do, and I thought I had it rough!
When I did hard copy doc. for a huge software system, I had 4 weeks after
code freeze to complete the documentation.
Now that we supply the doc. as online help, one of two situations occur,
depending upon circumstances:
1) Often, the programmers are making code changes right up until the day we
are supposed to ship the software. In this case, I am usually allowed to
make online help changes up to the day before release, giving the software
geeks a day to check my work.
2) The best scenario gave me 2 weeks after code freeze to complete the
helps. However, even then the programmers couldn't resist a few tweaks
here and there.
Welcome to the wonderful world of Documentation. Our deadline for the
printer is the same day as code freeze. However, we experience the same
thing: evenings and weekends right up until the end. In the latest
release, the programmers added two new options to the main menu, and I
only stumbled across it the weekend before code freeze. I had to re-shoot
all screens which showed the main menu. I think that the situation is the
same no matter who you work for. Documentation is just forgotten about and
very low on the totem pole.
Sorry this is so pessimistic, but that's the way it is. All I can say is:
"You're not alone".
Welcome to the Wonderful World of Technical Writing! <grin> Yes, that is
SOP almost everywhere I've ever worked! Here, it's even worse, since we
produce and duplicate our own software in-house. So... I have to have the
written docs done about 3 weeks prior to release of the product, in order
to get them printed and delivered on time. And in that last 3 weeks, there
is no telling what they will be doing to the product (they usually have the
UI frozen at some point, but on occasion the programmers have been known to
make a change that is critical -- although some of the time changes to be
made are discussed and depending on the impact on docs and stuff whether
the change is incorporated).
And yes, I always have last minute info in the READTHIS.TXT file. I figure
it gets read about as often as the manual. But I finally just let that one
go, since I've no control over it. The way I've finally figured it out:
the information is there, I've provided it, it is clear and concise. If the
person who should RTFM&D *doesn't*, well then, that's not my
responsibility. Our Tech Support people know the docs, and if someone calls
and has a problem, they point the person in the right direction (and by
that time, most of them are feeling sheepish that they didn't check the
> It puts a lot of stress on us, because developers are usually
giving us > serious technical changes right up to the day we send the
files to the > printer. We always have to work nights and weekends
near the end.
And once, again, Welcome!! Yes, this is the nature of the beast. I always
work up against a brick wall, and put in many long hours right before we
release a product! The only satisfaction I get is that I usually have all
docs written, printed and delivered *before* the programmers release the
product for production! <grin>
Here's our deal at xxx.
It's not always a hard and fast rule, but we got an agreement with our
development people that tech pubs will have x number of weeks _after_ the
code is "frozen" to finish the doc. For our situation, that means the
freeze before it goes to QC for testing.
As you know, our stuff is not so manageable, not shrink-wrapped, as is
in infancy, our process has yet to prove itself. Our doc still lags behind
the software, but we have about 35 books altogether. It would seem that at
your company the tech pubs department maybe should negotiate a publication
deadline beyond the software deadline. It's just not realistic to expect
the doc to be ready! But then, that's the software biz.
TECHWR-L List Information
To send a message about technical communication to 2500+ list readers,
E-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send administrative commands
ALL other questions or problems concerning the list
should go to the listowner, Eric Ray, at ejray -at- ionet -dot- net -dot-
Visit TechWhirl's Other Sites