DEADLINES summary (1)

[beth_staats -at- ARTISOFT -dot- COM]

     Tech writers,
     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
     info.

     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
     programmers!
     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
     complete.

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

     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-