Re: Anybody working in "Agile" ecosystems?

[John Cornellier <t_w -at- cornellier -dot- com>]

Hi, I'll try to answer in one go the questions raised by Kevin and Pete.

First, here's a simplified description of how I might work on such a project:

Day 1: Decide to deliver the doc in HTML format to be viewed in the user's system browser. Don't wait for approval, just start making the help file. If marketing has 
feedback we can port or retrofit. Agree with developers on help file path/name, and that all help button calls will use the dialog or window title as a call string. 
I create an empty help file at the agreed place; the developer adds a call string, and we both submit our revisions, which are built overnight.

Day 2: We have a new baseline that has a UI with a help button that calls an empty online help file. Yay! Progress! We've validated our linking system. I start 
filling in the help file with stuff I find in the product specs, such as they are. I submit my new iteration to the baseline.

Day 3: The developer calls the help and notices some stuff that's changed since the specs were done. We fix the doc immediately, together, on screen. I notice some 
new dialogs have been added, so we write up some new help together. The links just work on the agreed protocol. Submit new iteration to the baseline.

Day 4: We now have a new baseline incorporating informal reviews. The tester finds an unexpected UI behaviour -- we decide to document a workaround rather than 
changing the UI.

Days 5-20: keep incrementing, adding new stuff, fixing the old. At this point I'm not interested in format, I'm just using logical structure in form of h1, h2, etc.

Day 21: add an index, QC spelling, write the CSS, etc., put it out for FTR (Formal Technical Review), etc.

The end result is an HTML online document of about 400 paragraphs with context sensitivity, and basic navigation. The structure has a first part describing possible 
workflows, from which are hyperlinks to a reference section describing parameterization.

I also produced a white paper for marketing.

All of the content was written from scratch, as it's a new product. I did reuse material, e.g. the workflows came from some high-level "vision" type documents.

I wrote the HTML in an ASCII editor, and then towards the end applied some tools for automatic validation of the links, spelling, and W3C compliance. It's more 
efficient to do these at the end, since some material will be thrown away and replaced by other material.

There's no attempt to supply docs as "completed"-looking docs at every baseline. The goal is to take tiny steps, and keep putting work up for public review as soon 
as it's made. I didn't even bother to try to create a structural framework of blanks to be filled in, since the structure could change.

Regarding moving from one environment to another: I didn't have a laptop. Instread, the tester and I had a scooter for going up and down the corridors between 
offices.

As for evaluating the success of the project.... We'll see how it sells! We only had a small time overrun, so it was successful in that respect. I don't know about 
it being cheaper, but I do believe the quality is higher. It could be that there is a saving in testing costs. Because testing is happening earlier, small bugs are 
found early and fixed. If testing is started too late, then late-discovered small bugs can have a big knock-on effect which means that [already-tested up to then] 
code has to be changed (and retested).

In this project, there wasn't a prototype phase. The code evolved and was used (or thrown away) throughout the development cycle.

The agile concept is not quick generation of prototypes, followed by "proper architecting". The goal is be working on (and delivering/testing) the "real" product as 
early as possible in the project. Users tend not to be visionary. They don't know what they want until presented with something about which they can give meaningful 
feedback .... But developers can't know how users will react until they have meaningful feedback.... It's a connundrum. That's why the developer/tester/user exchange 
has to start early. Better to do the to-ing and fro-ing on small bits of code than to leave it to the end - when it may be too late.

All of what I say in the above three paragraphs applies as much to doc as to code.

John Cornellier



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A new book on Single Sourcing has been released by William Andrew
Publishing: _Single Sourcing: Building Modular Documentation_
is now available at: http://www.williamandrew.com/titles/1491.html.

Help Authoring Seminar 2003, coming soon to a city near you! Attend this
educational and affordable one-day seminar covering existing and emerging
trends in Help authoring technology. See http://www.ehelp.com/techwr-l2.

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