Re: Future of LedgerSMB: Ideas and RFC

[Chris Bennett <..hidden..>]

On Thu, May 19, 2011 at 11:16:44AM -0700, Chris Travers wrote:
> 
> 2)  Technical documentation
> 3)  Code documentation

User documentation is fine but coders need to have clear documentation for code.
Changing each items documentation as it changes needs to be a requirement for that coder.
No documentation for your function change, can't submit.
This is not a difficult requirement for a couple of changes in a module
> 
> Code documentation is something we have put a lot of work into
> throughout the 1.3 release cycle.  We do need to go through and review
> it again to ensure there isn't a lot that is missing or out of date,
> but there is a LOT of documentation available now in that area.
> Really to be effective code documentation needs to be a part of the
> development cycle and we have striven to do that.  It's not quite
> where we want it yet but it's coming along fast.
> 
> There are also some clear gaps in our code documentation and it's
> worth considering that we need to think carefully about how to address
> these.  It would be good to start another thread on this topic.  I
> will do that shortly.

Yes, I see that there is some code documention inline, but there is really no detailed man page
describing "the big picture". It would make getting started on coding much easier to see the
overall workflow for a variety of common tasks (from a coding point of view, not a users point of
view).
That's a writen document, a nice review.

A tougher project would be a nice sort of visual flow chart like this but graphic:
sub A($this, $that) -> sub B(etc) -> module whatever sub C

Chris, you would know this overflow best, but only giving a very rough start and handing off all
of the details to others would let this get done fast.
You have been doing almost too much of the work. It is very difficult to try and not do the detail
work but pass it on to others to struggle through. I learned this lesson the hard way with  my
business. Get some people started and let them fly or fail. But don't handhold. Very hard to do :)

I can code, but I would prefer to concentrate on the small picture, this "thing" needs to be
changed
I will give it  go.

I agree with the comments on SQL COMMENTS on the other thread.
Get all those in place, require them for any new functions (like I said above).
Then make an overall man page for interflow.
A flowchart could also be helpful.

It is pretty easy to get basics out of database. Just need to see general overflow and all will
be "clearish"

Thanks,
Chris Bennett