DEADLINES summ. Part 3

[beth_staats -at- ARTISOFT -dot- COM]

     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
     doesn't
     start until the UI is frozen." He would not guarantee dates until we had a
     frozen
     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
     product.

     Good luck - I hope you can use this response to point out the error of
     their ways.

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

     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.

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

     *sigh*
     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
     product.

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

     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
     docs first).

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

                               ...Game over...

                  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-