I previously worked at a company where the tech writer, in collaboration with development, was responsible for designing and writing the RS and the FS. The docs were highly detailed (about 3000 printed pages per year for a single writer), and were used to not only output and update specifications, but also online help and QA test cases--from a single source. It was initially difficult to maintain and design, but the beauty of it was that any change went through the tw, since all levels in the process were absolutely dependent on it. The writer never missed a trick. Following a single rigid methodology is like being stuck in a box. There is no single process that anyone should absolutely follow--we should constantly strive for new ideas if the results support them. S. Pollock Siemens PLM Software
> From: [EMAIL PROTECTED]> To: [EMAIL PROTECTED]; [email protected]> > Date: Mon, 29 Oct 2007 21:29:15 -0400> CC: > Subject: RE: radical revamping > of techpubs> > > 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: [EMAIL PROTECTED]: Re: radical > revamping of techpubsTo: [EMAIL PROTECTED]: [email protected]> > > > > > 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 <[EMAIL > PROTECTED]>To: Leslie Schwartz <[EMAIL PROTECTED]>; [EMAIL PROTECTED]: > 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: [EMAIL PROTECTED]> To: [EMAIL PROTECTED]; [EMAIL PROTECTED]; > [email protected]> 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: [EMAIL PROTECTED] > [mailto:[EMAIL PROTECTED] On> Behalf Of Technical Writer> Sent: Sunday, > October 28, 2007 5:47 PM> To: [EMAIL PROTECTED]; > [email protected]> 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: [EMAIL PROTECTED]: > re: radical revamping of techpubsTo: [EMAIL PROTECTED]:> [EMAIL PROTECTED], > 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 [EMAIL PROTECTED]> > _________________________________________________________________> 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 [EMAIL PROTECTED]> > Send > list messages to [EMAIL PROTECTED]> > To unsubscribe send a blank email to > > [EMAIL PROTECTED]> or visit > http://lists.frameusers.com/mailman/options/framers/lhs_emf%40pacbell.net> > > Send administrative questions to [EMAIL PROTECTED] 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 [EMAIL PROTECTED]> > Send > list messages to [EMAIL PROTECTED]> > To unsubscribe send a blank email to > > [EMAIL PROTECTED]> or visit > http://lists.frameusers.com/mailman/options/framers/spolloc1%40hotmail.com> > > Send administrative questions to [EMAIL PROTECTED] Visit> > http://www.frameusers.com/ for more resources and info. _________________________________________________________________ Peek-a-boo FREE Tricks & Treats for You! http://www.reallivemoms.com?ocid=TXT_TAGHM&loc=us_______________________________________________ You are currently subscribed to Framers as [EMAIL PROTECTED] Send list messages to [EMAIL PROTECTED] To unsubscribe send a blank email to [EMAIL PROTECTED] or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to [EMAIL PROTECTED] Visit http://www.frameusers.com/ for more resources and info.
