DEADLINES summ. Part 2
beth_staats -at- ARTISOFT -dot- COM
Wed, 26 Jun 1996 11:33:47 MTN
THIS IS THE SECOND PART of the message titled: DEADLINES summary
So sorry to hear about your company's "just throw it in the Readme
file" approach to documentation. No one reads Readmes. When's the last
time you read one? When's the last time one of your programmers read
Finally, after years and years, I work for a company that believes a
software product actually consists of three pieces: the code, the
testing, and the documentation. This assures that the customer gets a
well tested, well coded, _fully_ documented software product. All
pieces must be in place before the product is shipped.
After all, what good is that great feature the programmer put in the
software two weeks before shipping, if no one knows how to use it
(because it's not documented). You may try this argument on your
managers/director of development. You might even try a survey to give
proof to this statement: find a feature that was added to the
software, but only documented in the Readme file; call customers and
1) are you aware of feature xxx?
2) do you use feature xxx?
3) if yes, how do you use feature xxx? (to find out if they use it
4) if yes, how long did it take you to find feature xxx after you
installed the software - days, weeks, etc.?
Here's how we do development at my company.
1) We work from design documents called work requests (WR's). These
contain, at a minimum, a description of the programming to be done. WR's
can originate from marketing, customer service, etc. (I won't get into
how we choose which
work requests to work on - that's another story.)
2) Each WR first goes to a programmer who estimates the hours it will
take to code and enters additional design notes. Then the WR goes to
the QA analyst who will test the code. QA estimates how long it will
take to test and adds testing notes. Finally, the WR comes to the docs
dept. for a docs estimate and for additional notes about the docs
changes. (Many discussions occur during this process.)
3) After all _3_ are estimated, the hours are totaled and the total
estimate is added to a project plan. So, say we have 100 WR's for our
Version X Plan. After we estimate them, we come up with 300 hours of
programming/250 hours of testing/350 hours of docs. We then layout a
plan to come up with the release date, which in this example would be
about 2 1/2 months down the road.
This sounds like a lot of work if you haven't done it, but I can't
imagine not taking this approach. The first thing to start doing is
tracking your time so
you can do future estimates (this is a pain, but necessary).
My company took a year to fully implement this approach. It's a
painful process, but it was worth it. The quality of our product has
increased significantly and customer satisfaction is really high (not
the case before we took this approach.)
usually, its the other way round (lock the code, then finish updating
I don't know if it's SOP or not, but the department I work in at a
software company is now refusing to work on a doc until the executable
is 90% completed.
> _ there are always changes in the last three weeks of software
design. If we can't
> incorporate them at blueline, then they go into the Readme. And you
know how many users > > are faithful Readme readers. >
Not only that, if your company has a HelpDesk, you will find that the
numbers of calls to the Help Desk will decrease dramatically if the
documentation is based on a frozen executable.
> _ 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.
That is no small issue. Actually, the problem may lie with your
project managers who either estimate incorrectly, or view
documentation as not being an important part of the product.
I once had a project manager ask me to work up docs for a "form" (a
form is a "small executable" based entirely on specifications. When I
turned it in, I was asked where the screen shots were.
Bluelines? Are your manuals still being typeset and pasted up?
[Editor's note: We send them electronic copies, they make
folios/negatives, send us back bluelines - there's no pasteup.]
The last time I had to proof a blueline copy was 1985. We don't even
send hard copy masters to our print shop anymore. We simply print our
documents (integrated text, graphics, boilerplate material, and road
maps at a 77% reduction) to postscript, send the postscript file
to the print shop (it used to be via mag tape, but it might be direct
Internet transfer now), where it is loaded onto their Docutech printer
for printing. Because our text and graphics are integrated via Frame
and all manual manuscripts are "camera-ready" before they leave the
writer's hands, the writer proofs the layout (among other things)
before releasing the document for production. This has cut our lead
time considerably. Over the years, I've seen it shaved from as long as
16 weeks down to about two weeks now.
To answer your question, our manuals are due to the printer one to two
weeks after software code freeze. This is about three to four weeks
before "first customer ship" (the first software shipment is sent to
the first customer). This is more a matter of scheduling a flow of
several hard copy manuals for the printer. Actual turn-around time
for any particular manual is about a week to two weeks.
In the 16 years I've been a technical writer, I've constantly seen the
lead time between when text leaves the writers hands to finished
-- 1980-83: We had a lead time between 12 to 16 weeks. Writers had to
turn in their ASCII text files to the production group about five
weeks before code or hardware freeze (my record for having to pull a
manual back because of engineering changes, sometimes scrapping
printed books, was 11 times; a lot of waste in those days).
In production, the production folks entered format codes into the
ASCII text to typeset the text, did layout and paste up, drew line
art, and organized photo shoots. This in-house process usually took
about five or six weeks (and involved four or five production people)
before we even had anything to send to the printer. Pasted up master
boards were then sent to the print shop where paper or metal plates
were made, more photos were taken, they did the bluelines, and finally
a quantity run. Tabs were separately printed. The manual then had to
be hand assembled and boxed before it was ready to be shipped.
-- 1983-1986: I moved over to UNIX and began using nroff/troff. Page
layout and formatting moved into the hands of the writer, which cut
lead time for printing down to eight to 12 weeks. Writers had
standard space sizes to leave for illustrations, and we abandoned
photo-based illustrations and went completely to hand-drawn line art.
Writers produced page masters, which were still pasted up by
production along with the art. The print shop stage essentially
-- 1986-1990: I began working with my first WYSIWYG editor in 1986.
a concept! Writers now produced integrated tables, text, and graphics
and could actually see the manuscript as they created it!
Laser printed page masters became acceptable to the print shop.
Writers spooled page masters to the laser printer, proofed them, and
handed them over to the production department, which was now a single
person. That person prepared road maps, prepared tab art (which was
still pasted), did spot proofing, tacked on boilerplate information,
jobs with the print shop. Lead time moved to about five to six weeks.
Since then, a lot of advances have occurred on the print shop side.
In (I think) 1993 our print shop began to accept postscript files
instead of paper masters. We run a few scripts on our frame files
that produces a postscript file that produces masters at a 77%
reduction. These scripts tack on the boilerplate reader response and
front and back matter, and creates a
road map and tab file for the printer. After receiving the file, all
the print shop does is load up the file on their Docutech printer and
it spits out correct manuals. The Docutech has a CRT "head" that they
use to do an online proof before they print any actual paper. A lot
of the hand assembly has also been automated (collating, and so on).
I suppose this is more than you ever wanted to know.
Well, the xxx division of xxx isn't exactly software (my particular
product is logic analyzers), but our devices do incorporate software,
and it is the last thing to freeze. Nope, in the projects I have
seen, the entire team understands the manual will not be done until
the product is frozen. Because of this, we writers get to be part of
the project team. We even get some of the first protos and are
encouraged to abuse them. :-)
Now, this doesn't mean that life is completely rosy - my late manuals
were holding up shipment on the last project I was on, and you can bet
I was under pressure! But at least we aren't asked to document what
doesn't exist yet.
Someone else replied yesterday from the UK saying it is not the
norm...well I've worked in the western US for 8 years in the software
industry and I've -never- documented a complete product. If we're
printing manuals we often have to have the manual out six weeks before
the code (because of the large number of manuals the press has to
produce), then the
codes sometimes slips, so the manuals end up being done perhaps two
months before the code. Online help has been much better since it
freezes the same time the code does. But the reality I've seen is the
"code" is considered the product and they want to ship that ASAP so
they can start making money on it. We tech writers then just have to
do our best. It won't be perfect or 100% "right." Don't let that get
to you too much.
While we (writers/editors) have not been able to change the scenario
that documentation is done before code, we have made a lot of progress
on getting them to stick to design documents whenever possible
(localization also helps this battle). We also say over and over what
a change will do to the validity of the documentation, problems for
the user, and increased customer support calls. You learn some things
don't matter all that much (like when the toolbar doesn't match
exactly what the screen looks like, but the screen shot isn't talking
about the toolbar anyway) and other things matter a lot. We have made
progress so in some instances development delays crucial changes that
can't get documented or they redo the dates so we have time to
Yes, it's stressful. I'm sure documenting a complete product is much
easier (and takes considerably less time than constantly rewriting).
But I've heard of very few places where that's reality. I've worked
for four major software companies now and I have -yet- to finish my
documentation after the product was frozen.
NO, no, and again I say NO! To "freeze" the documentation BEFORE the
development work is finalized is akin to accepting your new home
before the builder has completed the plumbing and electrical work.
You never know what you'll get and a light switch might actually flush
As you have said, there are changes ALWAYS at the last minute that can
greatly affect the system and, therefore, the documentation. An even
greater issue is, what if the developers change something that is
already documented and the changes significantly affect the way the
system works? This is not uncommon, in fact its VERY common!
Management should allow documentation to keep pace with or slightly
lag the development effort. This ensures that the documents will be
accurate, useful and up-to-date. Unfortunately, in many cases, the
technical writers are brought in at the last possible moment and
expected to work a miracle even as the development effort is trying to
come to closure. It can be a very hectic time and if the development
effort is slowed for some reason, it can play havoc on the
documentation effort. This increases time to completion, project
costs, and stress.
My deadlines are usually the same as those used for the code. I do
"keep the customer/management informed" with drafts and changes as
needed. In fact, in some cases, the documentation may lag somewhat
behind the final code product because the customer has requested last
minute changes. The final draft may change for unforeseen items such
as scope and audience changes, presentation format, or political
reasons. My rule of thumb, thanks to Yogi Berra, is, "It ain't over
till its over."
Not much help, but as professional tech writers we owe it to
ourselves, our management, and most importantly our customers to put
out the best product possible.
You get to freeze your docs THREE WEEKS before the code??!! I could
die of envy!
We don't get to freeze our docs at all. We're an integrator - huge
systems with sometimes thousands or even millions of users (i.e.,
we're the main supplier of debit card transaction processing systems
in Canada). Our docs go to the printer the day after the system goes
"live". Because every system is unique, and they make changes as they
troubleshoot the install, there'd be no point in supplying info on the
pre-installed systems. We have to stay with the developers the whole
way, or we can't get done - if they make a change in the morning,
we've got it incorporated by 1 p.m. the same day.
Stress? Overtime? Work all night? Work Weekends? Yes - I believe that
is SOP - at least anyplace I've ever worked! And honestly, I think if
it weren't the case, the job wouldn't be as much fun!
Three weeks BEFORE the code is frozen? I'm assuming the idea is that
the printed docs will be back from the printer in three weeks, so that
they will be done when the code freezes. (First of all, it only takes
us a week to get our docs printed, because we just send our printer a
PostScript file and they print it directly using a Docutech, but
that's another issue.) Do you really ship as soon as the code
freezes? When does the code get tested????? [Editor's note: it gets
tested from early development on. Every time there's a new build it
gets tested and engineers fix bugs found. By the final build, there
are no bugs (only "doc bugs!").]
We have to have our manuals finished at the same time the code is
frozen. Then the docs are at the printers during the same week or two
that the code is being put through testing. If problems come up
during testing, or if they have to change something because of a
problem they found in testing, that information goes in the Readme
More recently, I work for a company that makes web publishers, and it
only takes a day or two to get the docs up online on the web. So, I
get the docs done when the code freezes, then the programmer's review
the docs while the QA people are testing the code, then I make their
review edits and put the docs up online by the time they're done
testing the code. (I like it when they find more bugs, because that
gives me more time!) I also give the docs to the QA people so they
can use them for testing, and so they can test the procedures I've
In response to your question about relative timing of code freezes and
finished manuals, where I work we are in a slightly better mode: we
must finish the manuals within a day or two after the actual code
IMO, Documentation should have two weeks after code freeze to complete
the manuals because end-game activities like final pagination,
indexing, and polishing summaries often require firm information.
But usually there is urgency surrounding delivery of the product, with
manuals, and we must rush the printer to get bound documents back to
us in time to ship. Night and weekend work at this stage is routine.
Frenzy prevails! I am interested in what you discover, as I had
assumed our situation is about average.
At xxx Software, we have different requirements for different products.
For our open systems products that run on UNIX, Windows NT, etc., the
writers are working on final manuals up until the last minute just like the
developers are fixing code at the last minute. For our mainframe products,
both the writers and developers have to "freeze" code and doc at the same
time, and they can't be working on it up until the last minute...that's
because the QA process for both doc and code is more formal/structured.
But, in any case, the writers don't have to freeze doc before the
developers have to freeze code...like at your company.
No! IMHO it's verging on the outrageous to ask for documentation to
be complete three weeks before the code is. I'm sure that the
majority of Technical Writers have worked on projects where
code-writing has slipped and run up to their deadlines (this happens
to me all the time). However, I would have thought that is virtually
impossible to produce reliable and fully accurate documentation
before the code is complete.
In my experience, Technical Writers seem to spend most of their time
trying to persuade Project Managers that we need a margin between the
completion of the code and the release of the product, in which we can
accommodate all of those 'last minute' changes which developers spend
most of their time producing. It sounds to me as if your managers
consider documentation to be little more than an irritation. Perhaps
they should have a look at the 'Cost of Documentation' thread on this
...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