[
https://issues.apache.org/jira/browse/OFBIZ-1387?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12544960
]
Jacques Le Roux commented on OFBIZ-1387:
----------------------------------------
An interesting discussion has taken place in dev ML :
http://www.nabble.com/Re%3A-svn-commit%3A-r597479----ofbiz-trunk-applications-party-entitydef-entitymodel.xml-tf4858720.html
I try to give an abstract below
The main idea is to avoid redundancy in documentation while giving enough and
useful informations without over-documenting (as it well known : too much
information kills information)
Pragmatically
. We should use a small method that adds spaces and changes capitalization from
fields names enough obvious to describe succinctly the fields (like in the form
widget : ModelFormField.getTitle)
. We should document non obvious fields and related concepts directly where
fields are defined (entitymodel.xml files). Though Scott suggested to document
those concepts at the data model level (like for instance why contact mechs are
not being deleted but expired). But where will stand this documentation at the
data model level is obscure to me. I guess out of the code in official
documentation (Confluence). There we could explain this kind of concepts which
are so often re-explained in ML. But who read documentation ? Not Skip for sure
who prefer to see it in the code ;o)
Theoritically (a point I like personnaly)
Jonathon : <<Documenting a single concept *concisely* in multiple places is
good. That's where "too much documentation" doesn't hold. Cross-references
between those multiple places will be better. A highly connected documentation
is like a highly connected brain with fast memory retrieval speeds.>> (I think
Jonathon means like Google did : bringing us synaptic connections, not only
neurons)
Defining concepts like Party and Contact Mech should be done concisely in a
glossary at a high level in the documentation with reference to OFBiz Bible
(Len SIlverston's books) when needed. Like Apache do it here :
http://www.apache.org/foundation/glossary.html.
And as suggested Jonathon above providing links (directly accessible thru
browser) or pointers (in code or such) will be a must of course.
Thanks to all
> comment Entities
> ----------------
>
> Key: OFBIZ-1387
> URL: https://issues.apache.org/jira/browse/OFBIZ-1387
> Project: OFBiz
> Issue Type: Task
> Components: accounting, content, ecommerce, framework, humanres,
> manufacturing, marketing, order, party, pos, product
> Reporter: BJ Freeman
> Assignee: Adrian Crum
> Attachments: party_entity_model.patch
>
>
> comment the Entities files in the entitymodel.xsd
> put a comment in this jira of the entities you are going to comment
> when you attact your patch number it with a date, so if you don't do the
> whole thing someone else can add to it, and not overwrite your patch.
> hope the committers don't mind this break in the rules.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
