Hi Pierre, I'm not sure what you mean by a "dedicated 'Help-OFBiz-Help' moment" (a high level JIRA improvement?) but I agree with the sentiment that help documentation needs work (a lot of it!).
This is critical if OFBiz is to be a world class open source application and development environment. There is much not to like in the current state of OFBiz help. The documentation is a mishmash of help directed to both Users and Developers. There should be at a minimum User, Developer and Administrator document sets. Each set should follow a template that defines a consistent topical outline. The OFBiz Help implementation is missing many of the features you expect in a robust help system (this is not to criticize the OFBiz help developers. They are resource constrained and given unlimited resources, I'm sure they would add many compelling features). See POC for presenting the current docs using Java Help to follow (this should/may work if you unpack to apache-tomcat-6.0.xx. It presents the Accounting help files in Java Help). IMHO any effort to document OFBiz for users should run in parallel with an effort to rationalize the OFBiz UI to implement best practices for usability. Also to follow is a list of usability guides (mostly inspired by Apple documentation on the Web.) From my experience when you try to document an OFBiz component you are immediately confronted with an inconsistent form implementations and/or flawed behavior. For that reason I think a documentation refactoring process should be to write a help doc that makes sense from a business use case / usability POV, then update the component to conform to the help doc "requirement". Following this process will at the same time create a set of requirements (guaranteed behavior) of OFBiz components, which today does not exist, along with the documentation and a conforming implementation. Doing both these at the same time will be more work but lead to a better outcome. This process could work through each OFBiz component in turn (no small job). It would require the dedication of at least two resources over a serious period of time. One to write the documentation (requirements BA stuff) and another to do the implementation. Between the requirements and implementation there would be room for comment by the community on the validity of the requirements (documentation). This work could be the basis for a Road-map for OFBiz improvement. I can contribute the DocBook help files but would want to work with the community on validation and implementation. I would like to begin with the HR Component because it is relativity simple (vs product, accounting, manufacturing etc.) and is required by organizations of any size. A better implementation of HR would open OFBiz HR for OTB use in many small to medium size organizations. Hope this moves the conversation forward in a constructive way. Tom ________________________________ From: Pierre Smits <pierre.sm...@gmail.com> To: u...@ofbiz.apache.org; dev@ofbiz.apache.org Sent: Monday, May 7, 2012 4:46 PM Subject: Re: Help OFBiz Help - day Scott, Contrary to what you and Jacopo (see this<http://ofbiz.markmail.org/search/?q=%22framework%2Fbase%20tests%20failing%22#query:%22framework%2Fbase%20tests%20failing%22%20from%3A%22Jacopo%20Cappellato%22+page:1+mid:2lceqdtlm5chbpm5+state:results>) believe, the developer mailing is for the developers of the project. That means intended for anyone participating in developing code ánd the community. It is not the Only-for-committers-who-do-code-only-and-where-other-communitiy-members-may-only-ask-limited-questions-per-issue" mailing list. Some community members may have chosen to only read the dev mail. I want to invite them as well to pariticpate in the "Help OFBiz Help"-day. Pierre 2012/5/7 Scott Gray <scott.g...@hotwaxmedia.com> > Please stop posting to both lists. > > Thanks > Scott > > On 8/05/2012, at 1:54 AM, Pierre Smits wrote: > > > Dear All, > > > > Did you know that OFBiz contains a solution delivering a help to each > > screen accessed? And do you use it? > > > > Currently for following applications/components help is available: > > > > - Accounting > > - Commonext > > - Content > > - Humanres > > - Marketing > > - Order > > - Party > > - Product > > - SpecialPurpose/Ebay > > - SpecialPurpose/EbayStore > > - SpecialPurpose/Example > > - SpecialPurpose/Googlebase > > - SpecialPurpose/ProjectMgr > > - SpecialPurpose/Scrum > > > > But, the help documents aren't complete (and in several cases not > > up-to-date) and for some applications/components totally missing (e.g. > > manufacturing). Also, documents mainly exist in English (only a few > > documents are in e.g. Dutch, Italian of French). > > > > As you would probably agree, the help document for a screen should be the > > first place to look when an end-user looks for help. > > > > What if we create a dedicated 'Help-OFBiz-Help' moment to improve and > > extend the help documents? > > Create the structure for applications that don't have it currently, > create > > the missing English documents for each screen accessible, embed it in the > > help structure and extend the localized versions? > > > > How do you feel about this plan? Please provide your feedback/thoughts on > > this and how you can contribute, in order for us to establish a plan. > > > > Regards, > > > > Pierre > >
