Re: Volunteer: OFBiz End User Documentation

[Si Chen]

Tibor,

I tried to do exactly what you're suggesting about a year ago when we  
developed the Financials module.  I tried to write a document which  
described all the business logic, data model, and processes.  If you  
look in the financials module there is a docs/ directory with a  
TechnicalDocs file in DocBook SGML format.

What I found was that it was extremely cumbersome and difficult to do  
things this way, because I was writing a document and then writing  
code.  If later the code couldn't follow exactly the original design,  
I'd have to fix the code, then fix the document again.  It is not  
impossible but would require a tremendous amount of discipline and  
effort to do this.

A better solution, in my opinion, is to comment the code better-- 
write more comments about the services, the Java methods, etc. that  
talk about what is going on, and comment the SECAs about what process  
each SECA is re-creating.  This would create documentation which is  
easier for developers to maintain and which another developer who is  
familiar with the basic structure of OFBiz would be able to work with.

This is what I'm trying to do know--as I look through code, I'm  
putting more comments and committing them.  I would encourage you and  
everybody else to do the same.  If you read through a service or some  
code that could use better comments, please send in a patch.

Si

On Jul 11, 2006, at 8:46 AM, tibor katelbach wrote:

I agree, that is the pb with such docs, they are heavy to write,  
because the
task is huge. But once it is done the main part is done, offcourse
maintenance is heavy but it could also be a new way of spotting  
precisly
what is new between versions and more readiable than a SVN upgrade.

we all took the effort of understanding processes and this would be  
a way to
share it. logs are shared but not exhaustive even the Verbose.

I did it for quite a few processes and when I communicate these  
docs to
other people needing a the same process, all they do is read it out.
if what they need is in there , then they dig in.
I often lost time by reading through loads of code and my answer  
was just
waiting at the end,
this way you go directly to the interesting section.

offcourse this gets really interesting only if we all participate.

just trying to help newcomers


On 7/11/06, Chris Howe <[EMAIL PROTECTED]> wrote:

I think that the easiest way to accomplish this is
through the logs.  Documenting these processes for
reference would be too burdonsome and maintenance
would be quite tedious.

--- tibor katelbach <[EMAIL PROTECTED]> wrote:

> Hi everyone
> I've been tagging along an idea of documenting
> algorythms of ofbiz
> processes.
>
> Since I started working with ofbiz, as always I
> found myself having to dig
> into existing code
> I found that the clearest way to understand how
> modules work is to rebuild
> the algorithm behind a process .
> A process could be a complete run through from url
> to controller to to
> Service , run through the Service to result , to
> Screen ...etc.
>
> by writting down the main elements of a process this
> draws quite a clear map
> of the algorithm behind the process, and especially
> is easily transmitable and readable by others. This
> also keeps from having
> to run through all code , all processes which would
> be the next step after
> reading the algo.
>
> WDYT ?
>
> I think it would be enourmously enrichining for
> people like myself wanting
> to understand quickly what does what, and what is
> done behind the scenes.
>
> Sometimes these algos quite large for processes like
> the chekout process
> here's a sample I gathered up for the tellafriend
> process:
> I list Service , Maps, redirections... a std format
> needs to be set up
>
> Form : tellafriend
> input : message, sendTo, sendFrom
>
> >>>> controller event :
> org.ofbiz.product.product.ProductEvents"
> invoke="tellAFriend"
>
> >>> dans le service tellafriend
>
> [GenericEntity:ProductStoreEmailSetting]
>

[bccAddress,null()][bodyScreenLocation,null()][ccAddress,null()] 
[contentType,null()][createdStamp,2006-04-21
> 15:06:47.428(java.sql.Timestamp)]
> [createdTxStamp,2006-04-21
> 15:06:46.848(java.sql.Timestamp
> )][emailType,PRDS_TELL_FRIEND(java.lang.String)]
>
[fromAddress,[EMAIL PROTECTED](java.lang.String
)][lastUpdatedStamp,2006-04-21
> 15:06:47.428(java.sql.Timestamp)]
> [lastUpdatedTxStamp,2006-04-21
> 15:06:46.848(java.sql.Timestamp
> )][productStoreId,910(java.lang.String)]
> [subject,${sendFrom} has sent you a
> link!(java.lang.String)]
>
[templatePath,/applications/petitbateau/templates/email/ 
tellafriend.ftl(
> java.lang.String)][xslfoAttachScreenLocation,null()]
>
> {
> templateData=
> [
> [EMAIL PROTECTED],
> message=qgfgsdf gsdf gsdf gsdfg sdf,
> [EMAIL PROTECTED],
>
pageUrl=http://localhost/petitbateau/control/product?product_id=94451
> ],
>
> [EMAIL PROTECTED],
>

templateName=X:/X_Dev/sequoiaerp/applications/petitbateau/ 
templates/email/tellafriend.ftl,
>
> sendCc=null,
> sendBcc=null,
> [EMAIL PROTECTED] has sent you a link!,
> [EMAIL PROTECTED],
> contentType=null}
>
>
>>>>dispatcher.runAsync("sendGenericNotificationEmail",
> context);
> >>>>org.ofbiz.content.email.NotificationServices"
> invoke="sendNotification(DispatchContext ctx, Map
> context)
>     >>>>method prepareNotification(ctx, context);
> //builds the body of the
> mail by rendering the corresponding ftl
> >>>>if body != null
> >>>>dispatcher.runSync("sendMail", emailContext);
> org.ofbiz.content.email.EmailServices"
> invoke="sendMail"
>
>
>
> Regards
> Tibor
>