radical revamping of techpubs

Tue Oct 30 09:00:18 PDT 2007

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: rinnie1 at 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!