Fw: Volunteer: OFBiz End User Documentation

[Jacques Le Roux]

For me wiki seems the easier at begining, Confluence of course http://docs.ofbiz.org/pages/listpages-dirview.action?key=OFBIZ

Thanks for your commitment, Tibor

Jacques
  ----- Original Message -----
  From: tibor katelbach
  To: [hidden email] ; Jacques Le Roux
  Sent: Thursday, July 13, 2006 3:01 PM
  Subject: Re: Volunteer: OFBiz End User Documentation


  I'm one step from action just wanted validation from the community ,
  and more important for the moderators to tell me where they beleive the best location for this would be ?
  in a doc folder of each application, and patched in the SVN ?
  in the wiki ? and in which one ?



  On 7/13/06, Jacques Le Roux < [hidden email]> wrote:
    Tibor,

    IMHO every effort is welcome. Why not trying this way ? It may improve with
    action...

    Jacques

    From: "tibor katelbach" < [hidden email] >


    > thx Si for your experience,
    > Commenting code is always a plus but eventhough it is heavy , I stick to
    > this idea as a usefull way to give and instant image of the algo behind a
    > process without having to go into every piece that constructs it.
    > This type of documentation should be maintained only when major changes are
    > made because it's not a detailed description.
    > Which isn't that often is it ?
    > in any case as I go forward I continue to gather them, and could commit them
    > into a docs folder of each process   containing application if you guys find
    > an interest in them.
    >
    > Regards
    > Tibor
    >
    >
    > On 7/12/06, Si Chen < [hidden email] > wrote:
    > >
    > > 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 < [hidden email]> 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 < [hidden email]> 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,[hidden email](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=
    > > >> > [
    > > >> > sendFrom= [hidden email] ,
    > > >> > message=qgfgsdf gsdf gsdf gsdfg sdf,
    > > >> > sendTo= [hidden email],
    > > >> >
    > > >> pageUrl= http://localhost/petitbateau/control/product?product_id=94451 
    > > >> > ],
    > > >> >
    > > >> > sendTo= [hidden email],
    > > >> >
    > > >>
    > > >> templateName=X:/X_Dev/sequoiaerp/applications/petitbateau/
    > > >> templates/email/tellafriend.ftl,
    > > >> >
    > > >> > sendCc=null,
    > > >> > sendBcc=null,
    > > >> > subject= [hidden email] has sent you a link!,
    > > >> > sendFrom=[hidden email],
    > > >> > 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
    > > >> >
    > > >>
    > > >>
    > >
    > >
    >