DEADLINES summ. Part 2

[beth_staats -at- ARTISOFT -dot- COM]

     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
     one?

     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
     ask

     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
     correctly)
     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
     the manuals!)

     ----------------------

     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
     manual shrink:

     -- 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
     remained unchanged.

     -- 1986-1990:  I began working with my first WYSIWYG editor in 1986.
     What
     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,
     and scheduled
     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
     document it.

     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
     a toilet.

     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
     file.

     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
     written.

     ----------------------------

     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
     freeze.

     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
     list.

     ...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-