[geeklog-devel] GL2: issue tracking system

[Chris Franklin]

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