TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
The problem here seems to be something that is relatively common in the
software development industry -- at least if you believe the venting that
takes place on this list (which I do). That problem is that your
deliverables are not considered part of the actual product. This perception
is exacerbated at some companies by tech writers reporting into the
marketing or support departments instead of being part of the development
organization.
Changing the perception that your deliverables are ancillary or somehow
secondary in importance is the first step in establishing a process that
allows you to meet the expectations of your peers and managers by delivering
on time. The bottom line: Educating your peers and managers in development,
product management, marketing, QA, and other interested parties is the only
way to succeed in this endeavor. So, don't give up quite yet on education!
What you call a "content moratorium" is something I would probably call a
feature freeze (no new functionality!) and/or GUI freeze (no further
modifications to the user interface!).
Here's how I might go about effecting change (I'm painting with broad brush
strokes, now):
1. Convince those responsible for scheduling product development and
deployment that your deliverables are integral to the success of the product
launch, and are indeed a part of the product as a whole. Therefore, you need
a reasonable amount of time AFTER the product has been finalized to finalize
YOUR deliverables. Outline the exact problems that last-minute changes to
the application cause. For example:
* Your procedures are dependent on stable functionality, and
therefore your procedures have to be rewritten every time
functionality changes.
* Your screenshots are dependent on a stable user interface,
and they have to retake a screenshot whenever something
changes in the corresponding window or dialog box in the UI.
Testing and QA often have the same dependencies that you may have, so it
pays to make friends with them, too.
2. Convince the schedule guru that you can't reasonably accomplish your goal
of delivering consistent, accurate, high-quality documentation without a
process that gives you time to do so. (This sounds like the same thing as
#1, but essentially it's just the same conclusion from two different
reasons.) Establish that a feature freeze and GUI freeze -- if necessary, a
complete code freeze -- would enable you to do this.
A feature/GUI/code freeze doesn't have to be a long time before the launch
of the product. It should be just enough time for you to retake any
screenshots, revise any changed procedures, and make any other final
modifications to your deliverables.
3. Last but not necessarily least, convince the development organization to
include documentation on its team (if you're not already). Establish that
you may be able to contribute as much as you gain from early involvement in
the design and development of the application. You can help out with editing
GUI text, testing the alpha product, providing insight on usability, and so
on. These duties may take you away from a pure documentation role early in
the dev process, but may establish a rapport with the developers and will
ultimately improve the quality of both the software and the documentation.
That's a lot of convincing to do, but it's definitely worth it in the end.
>That is, what can I reasonably demand for
>number of days/weeks that the product be
>stable in order to compose a final draft?
This of course totally depends on the size of your product and the amount of
documentation you have to produce. At one company where I documented part of
a very large CRM application, I was able to finalize screenshots for a 300
page manual in two days, taking notes on procedure changes along the way. I
then implemented the procedure changes over the course of two or three
additional days. After one day to have a peer edit and implement my editor's
comments, the manual was ready for QA -- all told, just over one work week.
At my present job, I was able to finalize content in a context-sensitive
help system (therefore no screenshots) for a relatively large workflow
management application in about three days, with a subsequent three-day
editing cycle. Give yourself a little buffer, and I think two to three weeks
is a perfectly reasonable time after a feature/GUI/code freeze to finalize
your deliverables -- at least for an average-sized product (if there is such
a thing).
Last-second thoughts in light of Bal's and Andrew's excellent comments:
While I agree that it pays to be nimble, and that process can become as much
of a problem as it is a solution, process is ultimately "doing things
efficiently and in the right way." The only way documentation can succeed in
Extreme Programming or Evolutionary Development environments (iterative
development cycles with very little lead time) is for doc to be involved in
the process as a whole. Without a defined process -- even a rudimentary one
-- that can't happen.
HTH! And apologies if I was preaching to the choir and ate up too much
bandwidth. ;)
Best regards,
Andrew Becraft
Documentation and Localization Manager
Internet Business Unit
TRADOS Seattle
505 5th Ave South, Suite 350
Seattle, WA 98104 USA
Phone: 206.438.5238
Fax: 206.438.5239
E-mail: andy -at- trados -dot- com
*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available 4/30/01 at http://www.devahelp.com or info -at- devahelp -dot- com
IPCC 01, the IEEE International Professional Communication Conference,
October 24-27, 2001 at historic La Fonda in Santa Fe, New Mexico, USA.
CALL FOR PAPERS OPEN UNTIL MARCH 15. http://ieeepcs.org/2001/
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
