Re: Documentation

[Jason Pincin <chardros@linuxkb.org>]

On Thu, May 04, 2000 at 11:19:09AM -0700, Aaron Turner wrote:
> > Definately need.  The roadmap (http://www.linuxkb.org/roadmap.html) I
> > thihk was a good start.  More detail needs to be added.  I'll soon shoot
> > what I see for Beta.  Perhaps others will do the same then and/or critique
> /me feels stupid now.  Yeah, that's what I was talking about.

Really?  I thought you were just tearing my document apart, saying it was
worthless :)

> > > - Generate a comprehensive list of technical issues we currently have 
> > > some examples:
> > > 	- Excessive DB queries for front page
> > > 	- Lack of scaleabilty
> > > 	- Performance of PHP for backend use
> > > 	- Complications due to use of PHP and Perl on front end
> > > 	- Lack of integration of search engine and web site
> > Yup.  Basically the reasoning for us believeing we need a new/better
> > solution.  How do you guys want to handle writing up a document such as
> > this?  Do we want one person to publish the initial doc, and allow others
> > to add/remove/change it?  Do we want everyone to write down there feelings
> > speratly, review all of them and form a master document?
> > I have no objections to starting these docs.  But if you guys can think of
> > another way that you'd prefer, lets talk about it.  This is what I meant
> > when I talked about defining a protocol in the Future doc.  I want to know
> > HOW we want to do documentation such as this... not just what needs done.
> My suggestion is this:
> - The "owner" of the doc, writes a quick draft (no more than an hours
> 	worth of work) as a RFC.  It shold be placed in devel or PS.
> - People have X days to check it out and add their comments to the doc.
> - After X days, people get on IRC to discuss; the owner leading the
> discussion based on the comments
> - After the IRC the owner posts the revised doc which is based on the
> notes taken during the irc chat.
> - The IRC chat log is attached to the document for historical reference
> (what was Joe thinking when he said that?)

Sounds like a superb suggestion to me.  I think all we need to do is
assign owners to documents and we can begin this cycle.  I'd be happy to
take ownership of the "Technical Problems to Overcome" document mentioned
above, unless someone else is willing to take it.  I only say I'm willing
to take it because I've become VERY aware of what our design limitations
are, especially with PHP, while developing functions.php3.  So I'll assume
it's mine to start the ball on unless someone else speaks up and claims
it.

> > > - Generate a list of features and their priority that our site will have.
> > > I'm not talking about backend features, rather features that the users
> > > will see on the front end.  Once these features are flushed out, we can
> > > then evaluate the order/requirements for the backend features.
> > Agreed.  I go back to "How do we want to generate this list"?  
> Same as suggestion.  I think you've already got a good idea what you'd
> like to see, that would be a good start.

Well... I guess I can start this one too.  Since i've already been
nominated for it, and do indeed have a "vision" :).  So, if someone else
does feel up to the task of taking the document on technical challenges,
feel free.  That is if you don't want to see me taking both of them.  But,
I have no problem taking both.  Just putting the option out there.

> > > - Continue documentation of PHP Objects & Actions
> > Dan - how's that documentor you were working on going?

Still awaiting response...

> 
> > > - Write Specs for all web forms/actions.  What fields, what they're for,
> > > what the actions should(n't) do with them.  No work on a form/action
> > > should be done until it has been spec'd and approved.
> > Could you elaborate on this a little more?  Are you talking pre or post
> > beta?  
> Pre-beta.  Basically what I see is that people don't understand what each
> form should do (lack of docs) and how much sanity checking should happen.
> The issue is that different people are taking different devlopment
> philosophies with the pages of the site.  Dan and Micah did extensive
> checking of input while Jason does little/none.

OK, what I see here is:

1) We need a set of general form design rules.  Standards that all forms
should confrm to.  

2) A spec for each individual form, detailing it's operation, data it
expects, etc.

Does this sound right?  If so - Dan, can you maybe ellaborate somewhat on
the problems you've faced as a form developer?  I'm probably not the best
one to figure out where the biggest problems lie.  So, if you could detail
your experience - perhaps it would provide the rest of us a good basis
from which to start something like this.

Thoughts everyone?


-- 
Jason Pincin
Linux Knowledge Base Project Leader (http://www.linuxkb.org/)
http://www.chardros.com/