Hans, I really like the descriptions for Product Store.
They are clear, concise and as you say available in both the forms and webtools. For purpose of discussion I'll the define the field descriptions as Reference Data*. Ideally there should be a 'golden copy' of the Reference Data in one place. The Product Store data is not in the entitymodel.xml but in ProductEntityLabels.xml. I wish it was in entitymodel.xml, the model should be responsible for knowing the meaning of it's data. Currently Product Store is the only entity recording field descriptions following the idiom: key="FieldDescription.Entity.fieldToDescribe"> key="FieldDescription.ProductStore.usePrimaryEmailUsername"> There are only 97 fields in the db labeled this way. As part of the documentation effort we need to create field descriptions. Where should we put the 'golden copy'? In the DB or establish a best practice following the idiom used for Product Store. There will still be a need to add field descriptionsin the Help to expand on and clarify the use of some fields. Pierre, This is as good a time as any to come up with a good set of field definitions. Should modifying the Entitymodel.xml or EntityLabels.xml be in scope. It's no more work (and adds move value) then maintenance of the HelpData.xml files with all their content stuff. Tom *"Reference data is any kind of data that is used solely to categorize other data found in a database, or solely for relating data in a database to information beyond the boundaries of the enterprise." (See http://www.information-management.com/issues/20060401/1051002-1.html) From: Hans Bakker <mailingl...@antwebsystems.com> To: dev@ofbiz.apache.org Cc: Tom Burns <tramseybu...@yahoo.com> Sent: Wednesday, May 9, 2012 8:57 AM Subject: Re: Help OFBiz Help - day Better store the field descriptions in the related entitymodel.xml files...then these descriptions show in webtools and in all the forms where they are used.... check the edit productstore for an example..... Regards, Hans On 05/09/2012 07:48 PM, Tom Burns wrote: > Pierre, > > 1. I have stubbed out the HR pages with a general format for each HR Main > menu item: > > * Overview > * List of field descriptions > * List of related detail pages > > I expect that format will evolve. > Likely work in coverage on setup, examples and some step by step how to / use > cases. > We should have some additional discussion on format and content later so > there is consistency across the applications. > > 2. Who is the documentation for: > * Business Users > * Developers > * Administrators > * Others TBD > > > I think we should stick with Business Users only on this pass. > > Information in the current documents addressed to other stakeholders should > be placed in a section that clearly identifies the intended target. > > > 3. Will you open a JIRA? > How about an umbrella issue for general discussion on guidelines and an issue > for each application. > There will need to be a place for discussion on application specific behavior > and review. > > Tom > > > ________________________________ > From: Pierre Smits<pierre.sm...@gmail.com> > To: dev@ofbiz.apache.org; Tom Burns<tramseybu...@yahoo.com> > Sent: Wednesday, May 9, 2012 3:01 AM > Subject: Re: Help OFBiz Help - day > > Dear all, > > Tom (Burns) has pledged his assistance to do the HRM help pages in US > English. Who wants to offer help as well to improve and extend the OFBiz > Help pages? You could work on Help pages for any specific > application/component or on Help pages in a specific language. > > I will do the structure for the Help pages in Manufacturing and start on > the Dutch locale. > > What would be a good moment to bring the patches to JIRA and have them > committed to trunk and the releases currently available to end-users? What > could be the 'Help OFBiz Help'-day? > > > Sascha and Christian: > May I ask you to assist in getting (some of) the German OFBiz Help pages > done? > > Erwan, Jacques and Nicolas: > May I ask you to assist in getting (some of) the French OFBiz Help pages > improved and extended? > > Adrian: > Could you assist in getting (some of) the OFBiz Help pages in the Queens > English improved and extended? > > Adam, Scott: > Will you assist in getting (some of) the OFBiz Help pages in US English > improved and extended? > > Regards, > > Pierre > > > > 2012/5/8 Pierre Smits<pierre.sm...@gmail.com> > >> Tom, >> >> Thank you for your replay and your insights. It is nice to read that you >> are willing to work on the English help pages for the HRM application in >> OFBiz. >> >> Actually, when I started the thread about the 'Help OFBiz Help-day I was >> thinking about the docbook help files in the helpdata folder under each >> application. Plus an update of the<application>HelpData.xml file of each >> application. >> >> With help from the community, it should be fairly easy to accomplish that >> every screen in every application/component visible to the (various) end >> users would deliver a help page on the topic viewed. >> >> Just a (small) description of what is to be expected or shown and what >> actions/functions can be executed would be a great starter. >> >> It would certainly be very beneficial to the end users the most and would >> help adoption of OFBiz. >> >> If we have that in place, then we could start thinking of working on a >> search functionailty for the help pages in OFBiz. >> >> Regards, >> >> Pierre >> >> >> 2012/5/8 Tom Burns<tramseybu...@yahoo.com> >> >>> Useability Guidelines >>> >>> ------------------------------ >>> *From:* Tom Burns<tramseybu...@yahoo.com> >>> *To:* "dev@ofbiz.apache.org"<dev@ofbiz.apache.org> >>> *Sent:* Monday, May 7, 2012 8:25 PM >>> >>> *Subject:* Re: Help OFBiz Help - day >>> >>> 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 >>>> >>>
