Re: Documentation

[Aaron Turner <aturner@linuxkb.org>]

On Fri, 5 May 2000, Jason Pincin wrote:

> Excellent summary Aaron.  Very well stated.  My comments below:
> 
> On Tue, May 02, 2000 at 10:25:35PM -0700, Aaron Turner wrote:
> > - Determine Milestones (ie. what features will be available for beta)
> 
> 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.

/me feels stupid now.  Yeah, that's what I was talking about.
 
> > - 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?)


> So, how do we wana tackle this one... this is one that should be done (I
> think) as we approach Beta... thoughts?
> 
> > - Generate a list of possible software we can use to fix the above (BLADE,
> > UdmSearch, custom Apache modules in C/Perl, etc) 
> 
> I think before we tackle this, we need to begin documenting and planning
> how the new backend will act and behave.  But this is a very important
> piece of the overall puzzle, i agree to that.

Agreed, figure out what are needs are, and THEN start researching
software.
 
> > - Assign people to research these technologies and generate reports on
> > their feasibility
> > 
> > - Determine primary language to write CORBA backend in: Python, C++, etc
> 
> On this topic, I really want to have a conversation or email discusssion
> with you (Aaron) and Dan - and yugami is VERY WELCOME to join in on that
> as he has CORBA experience.  As I told Aaron, I'm seriously thinking C or
> C++ for the OODS core.  But, this kind of subject doesn't need immediate
> attention... Beta does.

I agree, let's discuss this after beta.

> > - 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.

> > - Continue documentation of PHP Objects & Actions
> 
> Dan - how's that documentor you were working on going?
> 
> > - Pre-Define CORBA Objects & Actions
> 
> This should be the first stage of our oods initative. (IMHO)

/me nods

> > - 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.

> I think that I agree.  Can we come up with some examples?  Might clear it
> up a bit for me/others as to what yur thinking...
> 
> > I think we all should ignore OODS until after Beta.
> 
> Agreed.  Beta 1st.

--
Aaron Turner, Core Developer       http://vodka.linuxkb.org/~aturner/
Linux Knowledge Base Organization  http://www.linuxkb.org/
Because world domination requires quality open documentation.
aka: aturner@vicinity.com, aturner@pobox.com, ion_beam_head@ashtech.net
The difference between `Unstable' and `Usable' is only two characters: NT