[geeklog-devel] GL2: issue tracking system

[Tony Bibbs]

Chris, use cases are fine and I intended to do them but typically I do 
them in a completely separate document called a high-level use case 
specification.  That's not to say my approach is right, just what I'm use 
to.  Also, for open source stuff, the use cases also need a picture 
because it is  my experience that we don't read much so lots of pictures 
(when they make sense) is good.  

Good first stab!

--Tony

 On Wed, 12 Mar 2003, Chris Franklin 
wrote:

> hey everyone.
> 
> tony - great start on the requirements document for the GL2 issue tracking
> system.
> 
> I'm not sure how documentation works with the geeklog team or what
> everyone's comfort level is but I'd like to introduce my thoughts.
> Feedback is welcome.
> I think documentation is the key foundation to a succesful system and a
> "winnable" project.
> When designing software systems, particularly web applications, I think
> there are 4 basic doc sets which are necessary:
> 1) requirements document
> 2) context diagram and use cases
> 3) technical design document
> 4) source code doc (phpdoc)
> 
> I don't believe in writing large volumes of documentation. But a well
> designed system should have simple, concise, detailed documentation which
> allows people to understand each sub-system and the overall system in an
> intuitive way.
> 
> Over the past few years, I've gone through various iterations of how best to
> document software systems and I keep coming back to use cases as the
> foundation. Use cases are easy for software developers to understand b/c
> they take a big problem and break it down into smaller problems or units of
> work.  The context diagram is a wonderful way to describe a system b/c it's
> just a 1-page visual diagram with a line down the middle. On the left are
> the actors and on the right are all the actions (use cases) that the users
> can take. Problem is diagrams require tools like visio or a uml tools - I
> think it's simpler to manage as just an html file.
> 
> That all said, I've taken Tony's initial requirements document and added a
> section at the bottom which is similar to a context diagram:
> http://www.thefranklinweb.com/gl2/tracker_requirements.html
> 
> If everyone is comfortable going the use case route, the next steps are:
> 1) finish list of use cases - I came up with 17 but there are likely more
> 2) delve into the details of each use case
> 
> Once we have finished the requirements doc and corresponding use cases,
> technical design should begin - which would, of course, be the data model.
> 
> Regards,
> -C
> "franchr"
> 
> 
> -----Original Message-----
> From: geeklog-devel-admin at lists.geeklog.net
> [mailto:geeklog-devel-admin at lists.geeklog.net]On Behalf Of Tony Bibbs
> Sent: Tuesday, March 11, 2003 11:57 AM
> To: Geeklog Developers
> Subject: [geeklog-devel] Dwight, meet chris
> 
> 
> Dwight,
> 
> Instead of trying to hack a version of bugzilla or sf.net into GL2 I think
> we should just put together a real basic system for bug tracking.  I'll be
> putting together a shell requirements document and Chris will fill in the
> rest wtih you if that is OK.  It will need to have a web service interface
> to it but we should save that for last.  I will send a documetn out this
> week on it so you guys can get started with requirement and design.  I
> think you could get this up and down fairly quickly.  First major caveat
> is it will need to use GL2's A&A service so that the GL2 and bug trackign
> use same A&A components.  Not all of A&A is built but most is and for what
> isn't there I already have the API defined.
> 
> Dwight, if you can join IRC sometime and introduce yourself, chris's
> handle is franchr
> 
> --
> Tony Bibbs          "I guess you have to remember that those who don't
> tony at tonybibbs.com  hunt or fish often see those of us who do as
>                     harmlessly strange and sort of amusing. When you
>                     think about it, that might be a fair assessment."
>                     --Unknown
> 
> 
> _______________________________________________
> geeklog-devel mailing list
> geeklog-devel at lists.geeklog.net
> http://lists.geeklog.net/listinfo/geeklog-devel
> 
> 
> _______________________________________________
> geeklog-devel mailing list
> geeklog-devel at lists.geeklog.net
> http://lists.geeklog.net/listinfo/geeklog-devel
> 

-- 
Tony Bibbs          "I guess you have to remember that those who don't
tony at tonybibbs.com  hunt or fish often see those of us who do as      
                    harmlessly strange and sort of amusing. When you  
                    think about it, that might be a fair assessment." 
                    --Unknown