DEADLINES summary (1)
beth_staats -at- ARTISOFT -dot- COM
Wed, 26 Jun 1996 11:33:35 MTN
My apologies for the delay, but I was on one of those tight deadlines when
I wrote the inquiry and am just now getting back to a lighter workload. In
short, my message said:
> Where I work, we always have to have the manuals
> finished three weeks before the code is frozen.
> Is this S.O.P. in the software industry?
NUMBER OF REPLIES RECEIVED: 40
Number of those who said...
- it IS standard procedure in the industry: 11
- it isn't SOP, and...
- their deadline's the same as code freeze: 10
- their deadline's about a week after code freeze: 8
- their deadline's about two weeks after code's freeze: 6
- their deadline's at least three weeks after code freeze: 5
THE REPLIES (Part 1)
Following are all the replies, with names edited out. It's really
interesting reading -- I highly recommend it no matter how long it
takes. A huge THANK YOU, everyone, for the information!
P.S. If you'd like to speak to one or more of the writers, send me a snip
of the text whose author you'd like to talk to, and I'll send your request
on to the author. (Just trying to watch out for y'all's privacy.)
-Beth bstaats -at- artisoft -dot- com
I worked for xxx (formerly xxx) for three years, and we had a similar
problem. We took our frustrations to upper management, and amazingly they
agreed that something needed to change. They formed a committee, had gobs
of meetings, and eventually hammered out something called the "Product
Development Model." The Model specified how the entire development process
was to work. All aspects were covered--software development, training,
documentation. The Model was very writer-friendly. It basically told
developers that writers needed to be in the loop at all times, were
expected to give input on interface/design, and (here's the clincher),
could have FOUR WEEKS after a software deadline to finish the
documentation. Yes, I said four weeks. If a programmer wanted to change
the code during that four-week period, she had to get management
permission (rare case) or the change just didn't make it in that release
(usual case). Sounds ideal, right? The first year or so after the Model's
implementation was rough (old habits die hard). But management firmly
bought into the model--if they wouldn't have it never would have worked.
Eventually everyone was trained and their egos were smoothed, and the
Model worked quite well.
This type of system may not work for every company (our company had a
major software release every year or two, and interim releases every
quarter). The Model was a lifesaver for documentation, though. We'd done
too many all-nighters and too much unpaid overtime trying to keep up with
code-happy developers. Thank goodness management took our side!
Good luck with your query. If you have any questions, please let me know! I
look forward to reading about your results on TECHWR-L.
I write documentation for software developers, so my audience is
programmer-level, not end-user-level.
Typically, our docs are due 7 - 10 business days *after* code freeze. This
schedule allows the programmers to review the docs for technical accuracy,
and allows the writers to incorporate the latest and the greatest tech
The situation you described--docs due before code freeze--strikes me as
something out of Bizzaro World or Dilbert. In two years of tech writing
and subscription to techwr-l, I've never heard of such a thing. Some
pretty significant changes can occur in the last few days of a project, and
not having those changes reflected in the docs sounds to me like a
prescription for disgruntled customers. What is the financial health of
your organization? [Editor's note: Xlnt.]
At any rate, I wish you the best of luck!
I have now worked for about 7 different companies, all of whom had a
different attitude to this problem, but the _ONE_ thing they shared was
that the _KNEW_ the tech writers needed some time after product freeze -
the question was - how much? Where I was last, I was documentation
manager, and therefore was able to talk to product management and say
"Tough, you won't get it then, because we need time to..." (and the time
includes preparation and printing and binding and all, not just the last
tweaks). Where I am now they "freeze" the code 3 weeks before we are
supposed to be ready, but even with this margin, the Readme, which is
printed, not on disk, is about 30 pages thick, and the guy who works on it
has a nervous breakdown every release. ...and everyone knows that the
"freeze" is a milestone, not a reality...
My view is that Product Management (or Release Management, or whatever)
should NEVER state a final (planned) date until they have consulted with
ALL departments involved in contributing to the release contents - and
that includes documentation - if it can't be done by the time they are
thinking of, at least the know in advance, and can make whatever plans
they like. But to expect you to finish your work BEFORE the code is frozen
is, well let's just say "pretty dumb". As you say. who reads Readmes
anyway? You have got to convince your management that what you are
producing is as much a part of the product as the rest of the stuff (s/w,
h/w, whatever), and that it contributes to the professional (or otherwise)
appearance of the product - I bought some software two years ago which I
have used once, because the manual was absolutely useless - incorrect, in
the wrong order (the list of what was on the disk in chapter 7!), badly
written, badly illustrated - and I just threw it in the nearest WPB.
Need any help with the convincing - show them this mail, and I can also
supply more instances!
It was when I was writing software manuals. Actually, the typical situation
was somewhat worse. We would notify our client and build in that 3 week
period from the beginning of the project. The final delivery date would be
delayed a couple of times, so that by the time they really were going to
ship, they were frantic to get the product out the door because they'd just
squeak it in before the end of the quarter. We would freeze the copy --
which they didn't like -- and ship it to the printer. Everybody would be
stressed. They would keep developing features, making changes and then
they'd finally either hit a show stopper bug or admit that they weren't
going to make the end of the quarter, and the ship date would slip once
again and then they'd be upset because they were stuck with thousands of
printed copies that were going to be **really** out of date.
The 3 weeks is obviously driven by the print production cycle. There's not
much you can do about that. I think the feature/ship date fever is another
matter entirely, driven by the fact that development teams don't want to
restrict themselves to a feature set that's manageable and don't know how
to take other, real world constraints on the overall process into account.
They may be able to make a snazzy product that satisfies them, but if it
can't be realistically delivered into the customers hands in a reasonable
time frame, then that's a real world constraint.
This is one reason why electronic documentation makes a lot of sense. You
can ship a short, introductory manual with the product (and that can be
written without last minute stuff having to be in it), work on doc right up
to the drop dead day for final diskettes, and include a order form for
purchasing the printed doc which can follow at a three week delay without
delaying product ship.
Hoo boy, and I used to complain about having the _same_ deadline as the
Where I first worked, the code freeze was 6 weeks before the release date,
and the designers (i.e. programmers) HAD to inform us of any changes that
came up after the freeze. Last-minute changes were frowned upon by
management in general, so it was really nice.
Where I work now, we have the same deadline as the programmers --
unfortunately, the "code freeze" date is essentially the release date. How
are we supposed to incorporate the change they added the last day?
Fortunately, we can sometimes just say to the boss "well, that won't go
into the docs until the next release." Of course, he probably just says
"OK" because he knows that no one ever reads the manuals anyway... :-)
I've been pushing for a code freeze several weeks before the release (with
a docs deadline of 2 weeks before the release, so we have time to print),
so I'll be interested to hear the results of your survey -- I could use
some ammunition here too.
We usually have from 2 to 3 weeks following code freeze to complete our
documentation. Unfortunately, our development process separates UI
development from other code milestones and we end up with UI code slush
right up until our doc deadlines. That helps, but not enough in most cases.
I never finish documentation or online help until after the code is
finished. The only exemption to this is if they are changing the code to
match the documentation. In our place (10 techwhirlers) it is recognised
that the documentation can't be finished until after code)
It's SOP where I work. Developers don't know what a 'freeze date' is
apparently and yes, we are constantly either making last minute changes or
producing out of date doc. Now we have an added bonus - usability testing.
It's a great thing to respond to user feedback and make the appropriate
software changes, but not 10 days before the software release date.
Finally, some sanity!
I'm "lucky" at my company, which makes medical devices, because they can't
legally release software or devices without the documentation. This tends
to encourage project managers to include us up front and get our input on
the schedule. However, our project managers expect each team member to
provide them with a detailed time schedule.
Even when I haven't been lucky enough to have this kind of "power", I
always arranged a meeting with the project manager as soon as I was
assigned the project and had time to digest any design specs, schedules,
etc. At the meeting, I presented him/her the projected schedule, along
with potential pitfalls and solutions, and a documentation plan. This
helped me gain credibility with the team and showed the manager that I
wanted to make his/her job easier.
No. (To repeat many other responses, I'm sure.)
I have _never_ worked for a company that tried to document something that
wasn't done yet. My worst case scenario has been trying to have manuals
ready when the software was done. And that was very difficult and resulted
in some long hours and is almost impossible. The best arrangement has been
here at xxx and at xxx where manuals are expected to be done within 1-4
weeks _after_ the software is ready for release.
Keep in mind that the companies have no problem releasing the software
(especially beta) slightly before the docs.
At Intergraph, online docs are required in the releases before they can
ship. So the code _must_ be frozen weeks before they expect to deliver the
stuff. Hope you can get them to change that policy before it drives you
crazy _and_ causes customer satisfaction problems.
Your situation (doc deadline three weeks prior to the code freeze) sounds
typical. Tech writers need time to put the books together and get them into
print, code writers only need a few minutes to make a change to a file.
In the case at our company, we've been able to work up to the last minute
only if we're supplying printed docs (because we supply a limited amount of
software, so all we have to do is laser-print out a few last pages at the
last minute and slide them into a 3-ring binder).
But we're going on-line, and we now have to allow about two or three weeks
for the process of building the on-line files, and production of CDs. As a
result, yes we'll be freezing the docs before the code.
The worst case is one I'm working on right now. In addition to the docs
being on-line, they're also required to be translated into Spanish. I had
to freeze the docs last week for a project that will be delivered at the
end of July. It ships to the translators this week, and we'll likely get
it back just in time to press the CD and include it in the doc set. One of
the important features in this release hasn't even been designed yet, so
it's just barely mentioned in the docs. We'll do a couple of revisions,
but the docs will end up lagging four months behind the software until
February of next year.
This type of situation is nearly unavoidable. The only answer is to freeze
the code first, then allow the tech writers time to finish the docs.
Interestingly enough, -hardware- companies work that way.
The setup at your company sounds awful. It must be very demoralizing for
you. Of course, the situation of the programming being completed the
night before (or 5 minutes before!) the product goes out the door is
probably very common.
I only have one practical suggestion that might be helpful. With one
large project I worked on last year, we had the project broken down into
logical chunks and a grid was posted on the wall showing the status of
each modification. When I finished documenting a mod, I would go to the
grid and look for the next one that had been programmed and tested. Then,
I would work on that.
In this way, at least I was able to make good progress on the documentation
as the programming was done: so there was a relatively short delay between
the product being finished and fully tested, and the documentation being
Generally, I make a strong point that the testing, as well as the
programming, is done before the doc. I always find bugs in any case: but,
if the testers haven't been there first, the amount of bug- writing-up
seriously slows me down. Almost always, too, I either find typos (on
menus, screens, system messages etc.) that need to be fixed, or have
recommendations on how things could be presented a little differently to
make things a little easier for the user. I consider my job partially a
sort of quality control of the whole product, from the user's viewpoint.
I personally would never commit to producing the documentation before the
programming is done. In fact, for me it couldn't be done - for my screen
captures I need to be able to run the programs - which means of course that
they must exist and be in place - and also be able to run sample data for
the screen captures.
My rule is that I must know that what I'm saying in the documentation is
true. I'm giving the user instructions and data and I need to be satisfied
that the instructions and data are correct.
Perhaps I'm lucky to be in a situation where I can do that. But I think
that somehow or other you're going to have to figure out how to enlighten
your client (or employer) - if you want to bring about an improvement in
your final product. I wish you well!
I have a policy (and have had for more than a decade) that if the project
powers want an accurate set of docs, then I'll finish my docs AFTER frozen
code. However, if they're more concerned about getting the stuff out the
front door, then I'll give them what I got at their deadline--regardless of
any post doc changes. If they want last minute changes incorporated in the
Readme, so be it. And if there are still more changes, then the customers
What you're really saying here is whether the company is money-centric or
customer-centric. You can't put out _finished_ docs with your deadline
three weeks before the code is frozen. The last minute flurries of code
fixes, additions, deletions, dropped features bites ya every time.
Sorry, I couldn't finish this but I had to make the last email call <g>.
...TUNE IN TO NEXT MESSAGE FOR MORE REPLIES...
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