Prior Art

[Joseph Sinclair]

Bryan.ONeal@asu.edu wrote:

>Without proper documentation it is very difficult to
>1) Understand what your needs are and develop a solution to fit them:
>        I am not saying we write up a 30page purposely but some built points
>and a implantation map, suggesting some general object and their external
>functions and API names would be Extremely nice...  Especially since we could
>probably knock out the generals of the plane in just a few 1-2 hour meeting.
>  
>
Read the chapter on planning in eXtreme Programming eXplained, what 
you're thinking is what a release planning session is for.  The result 
is a set of story cards (much like CRC cards) that lay out the 
requirements for that release, along with a priority order, so the most 
important requirements can be implemented first, and the mass of 
relatively unimportant (to the customer) requirements are left to any 
"spare" time once the important things are complete and available for 
use.  Note also that lightweight methodologies don't say that we'll 
create no documentation, only that we'll create the least documentation 
that accomplishes the desired end (clear, concise, effective, efficient, 
and appropriately durable team communication).

>2) Utilize code others have developed.
>        Simply knowing what code is in your project and how to tape it will
>ensure you don't have to constantly reinvent the weal.
>  
>
We may have to do so in some cases, particularly where any existing code 
isn't released under a GPL-friendly license.  At other times, the 
existing code may be so poorly implemented that it's a better idea to 
write our own.  That said, We should certainly look into using existing 
code where it makes sense.

>3) Know where you are and where you're going 
>        We are already suffering from scope creep because we don't have a
>clearly defined scope.  If we did we would be able to say TicketMaster does
>not fit within our scope.  We can revisit it after the implementation of
>current phases is done.
>  
>
The release planning session will handle scope creep, in that as 
requests are prioritized, the time available gets consumed until all 
remaining requests fall into a "future release" bucket.  I've done a few 
projects with customers who always wanted to include more stuff at every 
meeting.  This practice of just adding in their requests, then having 
them choose what comes first, handled the issue in almost every case.  
They felt that their requests were heard and included in the project, 
and we were able to ensure that we didn't keep moving the deadline to 
fit more and more in.  The end result also had all of the things they 
felt were really important, without a bunch of stuff they wanted (or 
stuff we wanted), but they didn't need right away.  We don't have to say 
TicketMaster type functionality is out of scope, we just ask the primary 
customer (PLUG/AZOTO) if this is important enough to them to include in 
the next release, I understand that they don't feel that it is at this 
time.  (BTW, that's just an example.  In this case, I do feel 
TicketMaster is completely out of scope, in fact I think, if anyone is 
interested, that is belongs in a completely separate project all it's own).

>You can not just start coding without knowing what your coding!
>  
>
But you can start with limited information, only enough to code the next 
few features, and gather additional information as you progress.  If you 
ever reach a point where there's nobody in your customer base who needs 
more features enough to lay them out for you, then your system is 
feature complete.  You would maintain at that point (mostly bug-fix), 
and add features only when someone is willing to lay out their need.  
That avoids the M$ tactic of adding features just to generate a "reason" 
to upgrade to the latest "enhanced" version of software.

>Since most projects fail due to different operating styles of the volunteers,
>I feel agreement with vision, style, and environment to be extremely
>  
>
I agree completely

>important.  I, however, see defined scope, function maps, and vague class
>diagrams, to be key elements in facilitating a cohesive programming
>  
>
I see strong and effective team communication, coupled with a shared 
commitment to the project, and a unified overall vision of the desired 
results to be key.  Documents don't make good teams, they only record 
the point-in-time state of that team's shared vision.

>environment.  As for documenting your code, you should do it anyway, how else
>will you know what you did six months latter, let alone have some one else
>  
>
Code documentation is required.  Adherence to team development standards 
is required.  These are things that, when followed, support strong and 
effective team communication, and when not followed threaten the 
cohesiveness of the team.  I have a fairly complete coding standards 
document that I've used before for some platforms.  If the coding team 
chooses a platform I don't have standards for, I'll look up and compile 
a standards document for that platform during the first coding iteration.

>know what you did. However, if the rest of the group feels different, then I
>must assume I am a hindrance to the implementation and will gracefully remove
>my name from the development team and quietly watch, with keen interest, from
>the sidelines.  
>  
>
Please don't step aside.  We may not generate as much documentation, or 
in the form you're used to, but we'll generate *enough* documentation, 
and it'll all be useful, since anything not useful gets discarded 
(except for historical copies) at the end of each iteration.

>Although, in truth, we may be disagreeing du to a misunderstanding on what
>documentation is and should be.  Sort of a comparison of Tangerines and
>Oranges ;)
>
>Perhaps we can find a good Tangelo to agree on; perhaps not.
>  
>
I feel that a close reading of the principles of lightweight 
documentation rules would produce that Tangelo for us.  Please take the 
time to look into it, I think you'll like what you find.

>
>On Fri, 25 Mar 2005, Joseph Sinclair wrote:
><<SNIP>>
>