Re: Future of LedgerSMB: Ideas and RFC

[Chris Travers <..hidden..>]

On Fri, May 20, 2011 at 7:20 AM, Chris Bennett
<..hidden..> wrote:
> 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

In cases where there is a change to desired behavior I would agree
with you.  In cases where the change is still in line with
documentation, I am not sure that's necessary.

Also I don't think it's practical to fully document the functions in
the files in bin/ (that we inherited from SL) because quite frankly
the code is such a mess that troubleshooting usually has to begin with
a new review of the code.  For the files in scripts, I am also not
sure that documenting every function as a function call is helpful
simply because 90% of every piece there is going to be boilerplate.
Maybe it would be better to put in Perl comments (rather than POD)
identifying which screens are rendered by which functions, and have
the flow documented in the technical documentation of the manual.

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

There's a code overview in the manual but it's a little out of date
and needs to be revisited and expanded.

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

What would folks need from me?

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

What do you think a flow chart should cover?  Are we talking about an
architecture diagram?

>
> It is pretty easy to get basics out of database. Just need to see general overflow and all will
> be "clearish"
>
Thanks for the thoughts :-)

Best Wishes,
Chris Travers