Review of 19 April 2006 Draft of State in Web application design

This note is in fulfillment of my action [1] to review the latest draft of 
the "state finding" [2].  My overall comments are summarized in this 
email.  I also had quite a few detailed comments, both editorial and 
otherwise.  The best way I could find to capture those was to use MS Word 
revision marking to produce an edited HTML file, a copy of which is 
attached.  I apologize that this may not be the most standards-compliant 
or accessible form of HTML, but it was the most practical option I could 
find.  I did preface all of my comments with two asterisks ("**"), which 
should make them easier to find if color doesn't do it for you. 

Anyway, my overall comments are:

* In its current form, this seems to be more of a broad tutorial on 
stateful applications than a finding on good practice.  As a series of 
XML.Com articles, this would need just a bit of refinement to be really 
great.  As a TAG finding, I think it should be significantly refocussed on 
explaining what is good practice and what isn't.  Most likely, this should 
be in the form of explicit good practice notes.

* Needs to be significantly shorter.  I think the meat is in the later 
sections.  I would drop entirely or radically compress the earlier 
sections.  See suggestions in the marked up copy.   My intuition is that 
this should be no more than 1/2 the current length.

* I think it's a good thing if you can summarize five or fewer key points 
(preferably 3 or so) that are the core of each TAG finding.  I'm not 
finding them in this one.   What are the few things we want every reader 
to get from this finding?

* I think the text would be much more effective if it were considerably 
tightened.  Many of the sentences have phrases like:  "It is important for 
our analysis to point out that...".  Many of these can be reworded to be 
both shorter and more effective, or eliminated entirely.  I've made some 
sample editorial changes in the attached file, but they were done in some 
haste and are far from perfect.  Take them as generally suggestive of the 
sort of tightening I'd consider.  I only did detailed comments on the 
first half or so;  in the second half I highlighted only a few major 
issues.  I'd prefer to do a more detailed review once a redraft is 
available.

Having said all that, I think Dave is onto something here.  I think this 
is an important area, and that within this is the start of a very 
effective finding.  As noted above, I think it should be more focussed on 
giving specific advice, particularly in areas that are confusing or where 
the tradeoffs are difficult. 

Noah

[1] http://www.w3.org/2006/05/30-tagmem-minutes.html#action04
[2] http://www.w3.org/2001/tag/doc/state.html



--------------------------------------
Noah Mendelsohn 
IBM Corporation
One Rogers Street
Cambridge, MA 02142
1-617-693-4036
--------------------------------------