I neither inferred nor implied that you say TWs have no place at any point in
a project. You did, however, clearly state that in response to comments about
involvement of TW or doc mgr early in the product development, "At that stage,
TWs have no place, whether department managers, full partner
participant-stakeholders, or something else."
Your assumption is that if a TW is involved, it is for the purpose of
creating a document. While it is often true that creating documents early in
product development simply creates files to obsolete/trash due to sidelined
ideas, you are completely missing the intent. The involvement of TW/doc mgr
early on is not initially for writing the doc as muc as it is for user
advocacy, sanity checks of UIS or other specs from a user-driven perspective,
as well as getting buy-in and resource allocation far enough in advance that
creating a remotely usable document is at all feasible. The later the TW is
inserted into the process, the harder it is to create anything better than
basic functionally-driven documents. Several others have echoed this same
point, and it is well-documented. It's not just a one or three personal
experience basis. There are a lot more use cases out there - a survey of books
from leaders in our industry like Hackos and others clearly reveals
this. Look also at the breadth of comments in response from other listers
here, too.
FWIW, *all* of the companies where I worked and where TWs were involved
early on in the product life cycle, Agile is the software used for managing
product development. Having a doc listed by part number on the BOM of a
product (and in the case of Help, as a part number for the software build
list) ensured earlier integration of TWs and ultimately produced higher
quality documents. Use of Agile and early involvement of TW resources are not
mutually exclusive. Now, whether some companies using Agile as the governance
of product life cycle choose to use that as an *excuse* NOT to include TWs
until late in the game may be your personal experience, but that does not
necessarily mean it's the way of the future, or that Agile implementation
would be causal to the effect of late involvement of writers. Bringing in a
"hired gun" writer late in the project as almost an afterthought is a trend,
yes, but it has a lot more to do with the bottom line (dollars, pounds,
euros, yens, etc.) than it does with whether the company uses Agile. If there
aren't multiple products with ongoing development and overlapping product life
cycles, it's simply cheaper to pay a contractor twice as much for a couple of
months than keep writers on staff longterm in some industries and/or R&D
environments, depending on the company dynamics, market forces, and product
life cycles.
Rene Stephenson
Technical Writer <tekwrytr at hotmail.com> wrote: .hmmessage P {
margin:0px; padding:0px } body.hmmessage { FONT-SIZE: 10pt;
FONT-FAMILY:Tahoma } I did not categorically state that TWs have no place
at any point in a project. To so state is misleading, and implies that I said
TWs are useless. I said that in an ambiguous, undefined software project
(which many, including multi-million dollar, tend to be), it is pointless to
create documentation of an application that may--and probably will--change at
the next iteration.
The fault is not with TWs; the fault is with agile developers who cater to
the egos of senior management, charging dearly to maintain the illusion that
management can have whatever toy they happen to think of, at anytime in the
development process. Because that type of development is becoming more and
more mainstream, it seriously affects TWs.
From the standpoint of an agile developer, "it all pays the same." What is
presented as "control" and "involvement" to management is a ploy to curry
favor and extend the development period. It is immensely profitable, and
management, in general, seems to believe the almost obsequious demeanor of
agile developers preferable to the old-style "you can't have this even if you
are the CEO, because it was not filed in triplicate as an initial requirement."
Ultimately, the situation is a response to the "developer as hostage holder"
mentality that considered management as only useful to pay the bills.
Management wants (at least the illusion of) control, and agile developers have
learned to play to that weakness. In so doing, they are diminishing the role
of TWs. Pretty simple stuff, not particularly my opinion, nor representative
of one or three cases of personal involvement in projects. Like it or not, it
is the future.
http://www.tekwrytrs.com/
Specializing in the Design, Development, and Production of:
Technical Documentation - Online Content - Enterprise Websites
---------------------------------
Date: Mon, 29 Oct 2007 19:46:00 -0700
From: rinn...@yahoo.com
Subject: RE: radical revamping of techpubs
To: tekwrytr at hotmail.com; lhs_emf at pacbell.net; framers at
lists.frameusers.com
TW dept managers or directors in particular do have a place in
developmental stages. They provide user advocacy in the initial stages, when
the development is most nebulous, providing direction and focus toward the
common goal of the team: happy customers who like the product and want to buy
more. From the TW perspective, the TW mgr/dir gathers info about headcount
impact, resource allocation dynamics, etc.
You simply cannot categorically state that TWs have no place at any point in
a project, because there are too many successful use cases that prove to the
contrary, at least 3 of my previous gigs being examples thereof. It depends
on the pace of development and the length of the product life cycle, among
other things. The faster the products develop and the shorter the product life
cycle is, the more critical it is to have TW integration at the earliest phase.
Creating user assistance is indeed a necessary task, but it is only one of
many that TWs perform. User advocacy ? getting the user expectations back up
the chain into the ears of those who can impact what the users end up getting
? is at least as important as the more common task of user assistance. If all
the user needs is assistance, they'll just ring off the hook with tech support
or customer service. User advocacy ensures higher quality products that lower
call volume to tech support and customer service. Writing good, usable Help in
terms that the user understands is another way to drop the call volume. But,
rely on either without the other and you don't reap the maximum benefit of TW
staff.
Rene Stephenson
Technical Writer <tekwrytr at hotmail.com> wrote:
That is a very big if. A full partner participant-stakeholder, or more likely
the department manager? It is more likely that the software developers,
business analysts, and the project manager are collaborating to get a decent
set of requirements down. At that stage, TWs have no place, whether department
managers, full partner participant-stakeholders, or something else.
When the requirements are determined, and possibly after several iterations,
possibly after a prototype is up and running, TWs might be brought in. Even at
that stage, it is early, because the GUI crew may not have the interface
coded, the developers might not have the functionality carved in stone, and
everything is still uncertain (in regards to exactly what the final product
will be and do).
TWs complete a very necessary task; creating user assistance. Until the final
iteration, until all the requirements have been met, until there is little or
no possibility of changes to the end product, there is little point in
generating documentation that might become obsolete at the next iteration.
http://www.tekwrytrs.com/Specializing in the Design, Development, and
Production of:Technical Documentation - Online Content - Enterprise Websites
Date: Mon, 29 Oct 2007 08:26:46 -0700From: lhs_emf at pacbell.netSubject: Re:
radical revamping of techpubsTo: tekwrytr at hotmail.comCC: framers at
lists.frameusers.com
Actually, I disagee, if the TW is a full partner participant - stakeholder, or
more likely the department manager in the scenario you are discussing, they
should also participate early on to get the sense of the uncertainty and what
those issues are, at the very least these issues are going to affect their
scheduling and the expectations they have to deal with.
----- Original Message ----From: Technical Writer To: Leslie Schwartz ;
framers at lists.frameusers.comSent: Monday, October 29, 2007 8:44:16
AMSubject: RE: radical revamping of techpubs
I agree wholeheartedly. That is not the issue. The issue goes back to the BA
interpretation of (and translation of) the software requirements. If there is
a high level of certainty on the client side about what the finished product
should be, TWs should start early. If not, and it is essentially a fishing
expedition with ambiguous outcome, TWs are only useful at the last.
Unfortunately, the "agile" methodologies strongly sell the sense of control to
executives, pushing the idea that they can develop on the fly, adding and
removing "requirements" as the executives see fit.
http://www.tekwrytrs.com/Specializing in the Design, Development, and
Production of:Technical Documentation - Online Content - Enterprise Websites>
From: lhs_emf at pacbell.net> To: tekwrytr at hotmail.com; bhechter at
objectives.ca; framers at lists.frameusers.com> Subject: RE: radical revamping
of techpubs> Date: Sun, 28 Oct 2007 19:04:10 -0500> > I belong to several
message - interest groups and I am
used to hearing people give their opinions in a bombastic manner. So its no>
big deal to see that happening here. But if this discussion is to have any
real value it will be to share our perspectives with> others and learn
something about points of view's entirely different than our own, which
requires some tolerance and mutual respect.> > > My view and experience is
that it definitely helps to get the TW involved early on, but it?s a waste of
time for them to sit all the> way through each meeting, and for the entire
duration of each meeting.> > Marketing requirements documents and engineering
specification documents, if they are adequately written will help the TW
formulate> the user documentation at a fairly early stage, but the bulk of the
documentation effort comes towards the end of the development> cycle. And
ideally the writer of the user guide if that is they type of documentation we
are discussing now, should be a> knowledgeable user with some fresh
insights into the learning curve the novice user will face, and some empathy
for that new user.> > Ignoring the need for documentation, putting it off
until the last moment is a formula for poor quality documentation.> > - In my
humble opinion.> > Have a great work week!> > Leslie> > > -----Original
Message-----> From: framers-bounces+lhs_emf=pacbell.net at
lists.frameusers.com [mailto:framers-bounces+lhs_emf=pacbell.net at
lists.frameusers.com] On> Behalf Of Technical Writer> Sent: Sunday, October
28, 2007 5:47 PM> To: bhechter at objectives.ca; framers at
lists.frameusers.com> Subject: RE: radical revamping of techpubs> > > Well, a
difference of opinion is what makes a horse race. Iterative software methods
do not require iterative documentation methods;> in most cases, documentation
before the last iteration is considered both wasteful and useless. While I
have a great deal of respect> for Steve McConnell, proposing early draft user
guides as a replacement for
requirement specs is a bit off the road. > > If you develop software, and
intend to use early draft user guides instead of requirements, you are going
to be greeting the folks> at Wal-Mart rather than trying to pull back a
contract or two from Bangalore. The statement is at odds with most developers'
(and> most business analysts') understanding of "requirements." Putting an
occasional "agile" into a sentence doesn't make the process any> more
reasonable. > > I didn't invent the idea of ignoring documentation until the
final product is ready (or almost ready) to ship. Far more intelligent,>
competent, and capable people than me have decided that "involving TWs from
the early stages of development" is only useful when the> end product is
carved in stone before the first line of code is written. That, for better of
worse, is rarely the case.> > Lastly, given that about a third of all software
projects, agile or otherwise, fail so badly they are abandoned, if you
ignore> documentation completely, you have a one in three chance of coming
out ahead when the project flops because you have at least saved> the cost of
documentation.> http://www.tekwrytrs.com/Specializing in the Design,
Development, and Production of:Technical Documentation - Online Content ->
Enterprise Websites> > > Date: Sun, 28 Oct 2007 12:21:17 -0700From: bhechter
at yahoo.comSubject: re: radical revamping of techpubsTo: tekwrytr at
hotmail.comCC:> framers at lists.frameusers.comSorry, but I find the thread
both:a) Off-topicb) Misleading. Iterative sofware methods require iterative>
documentation methods, but by no means do they eliminate the parallel need for
early draft user manuals. In fact, Steve McConnell> (Code Complete) proposes
early draft user guides as an agile replacement for requirements specs.Ben>
Because the application itself> is built in an iterative process, rather than
> being carved in stone, reacting to feedback from the client,
documentation > before> the last minute is pointless. The reason should be
obvious; the > application being documented in the early stages bears little>
resemblance > to the application delivered. Ben Hechter Vancouver BC bhechter
at yahoo.com>
_________________________________________________________________> Windows
Live Hotmail and Microsoft Office Outlook ? together at last. Get it now.>
http://office.microsoft.com/en-us/outlook/HA102225181033.aspx?pid=CL100626971033_______________________________________________>
> > You are currently subscribed to Framers as lhs_emf at pacbell.net.> >
Send list messages to framers at lists.frameusers.com.> > To unsubscribe send
a blank email to > framers-unsubscribe at lists.frameusers.com> or visit
http://lists.frameusers.com/mailman/options/framers/lhs_emf%40pacbell.net> >
Send administrative questions to listadmin at frameusers.com. Visit>
http://www.frameusers.com/ for more resources and info.> Boo! Scare away
worms, viruses and
so much more! Try Windows Live OneCare! Try now!
_________________________________________________________________
Boo! Scare away worms, viruses and so much more! Try Windows Live OneCare!
http://onecare.live.com/standard/en-us/purchase/trial.aspx?s_cid=wl_hotmailnews_______________________________________________
You are currently subscribed to Framers as rinnie1 at yahoo.com.
Send list messages to framers at lists.frameusers.com.
To unsubscribe send a blank email to
framers-unsubscribe at lists.frameusers.com
or visit http://lists.frameusers.com/mailman/options/framers/rinnie1%40yahoo.com
Send administrative questions to listadmin at frameusers.com. Visit
http://www.frameusers.com/ for more resources and info.
---------------------------------
Help yourself to FREE treats served up daily at the Messenger Caf?. Stop by
today!
