http://ofbiz.116.s1.nabble.com/Re-svn-commit-r597479-ofbiz-trunk-applications-party-entitydef-entitymodel-xml-tp185726p185740.html
> See Jonathon, I always said that you were smarter than me.
>
> Skip
>
> -----Original Message-----
> From: Jonathon -- Improov [mailto:
[hidden email]]
> Sent: Thursday, November 22, 2007 8:51 PM
> To:
[hidden email]
> Subject: Re: svn commit: r597479 -
> /ofbiz/trunk/applications/party/entitydef/entitymodel.xml
>
>
> Yeah, the additional documentation adds "zero" to the documentation value.
>
> For eg, field "contactMechTypeId" is described as "Contact mechanism type
> ID". Would be more
> descriptive to say "unique identifier for a contact mechanism (see *) type".
> And somewhere else at
> "*", we have:
>
> "A contact mechanism is a way or method to contact an entity like a Person
> or Company. Examples
> are phone numbers, postal addresses, etc."
>
> As for "too much documentation", that is true if the documentation is not
> concise. For eg,
>
> "Field contactMechTypeId is a contact mechanism type ID. It is an ID that
> identifies a contact
> mechanism type. A contact mechanism type is a type of contact mechanism. The
> ID identifies one
> instance of such a contact mechanism type. The ID uniquely identifies the
> contact mechanism type."
>
> Only the last sentence really means something. A reader has to plough
> through a lot of fluff to
> get there!
>
> "Too much documentation" is also true when speaking to the wrong audience,
> like telling a group of
> physicists: "gravity is the force we experience from a mass".
>
> I get the impression that OFBiz documentation is targeted at OFBiz experts,
> or at least competent
> developers.
>
> 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.
> Any neurologist here? :) I know there's a microbiologist, I think.
>
> Jonathon
>
> David E Jones wrote:
>> Skip,
>>
>> Did you look at the stuff in this commit? If not please do so and
>> re-comment.
>>
>> As for too much documentation, of course there is such a thing! People
>> have a hard time with documentation (ie not reading it...), so the less
>> the better. It's even great if they can find documents that describe
>> just what they are looking for, but even that gets into a "too much
>> documentation" because if you tried to create documentation for
>> everything anyone might want to do the volume of the docs would be so
>> huge that chances no one would ever find the document they are looking
> for.
>> In general a nice balance is just reducing redundancy and trying to know
>> your audience. There are lots of audiences (like people who don't know
>> the difference between an invoice and order) that we probably won't be
>> helping by designating as an audience. People in that circumstance
>> should first learn about business, then about business systems, and then
>> about OFBiz. They will be MUCH happier. The same pattern applies on a
>> technical level. If we included J2EE 101, the Tomcat docs, etc, etc our
>> docs would be much bigger but less useful because of it.
>>
>> -David
>>
>>
>> On Nov 22, 2007, at 7:42 PM, skip@thedevers wrote:
>>
>>> I have two points to add here. First, there is no such thing as too much
>>> documentation. Even if it can be found elsewhere, having it within
>>> the same
>>> spot where someone might expect to find it might be a good thing.
>>>
>>> Second, what might be "obvious" for one might be horribly complex for
>>> someone else.
>>>
>>> I vote to have more documentation, especially in that it cannot hurt.
>>>
>>> Skip
>>>
>>> -----Original Message-----
>>> From: David E Jones [mailto:
[hidden email]]
>>> Sent: Thursday, November 22, 2007 2:00 PM
>>> To:
[hidden email]
>>> Cc:
[hidden email]
>>> Subject: Re: svn commit: r597479 -
>>> /ofbiz/trunk/applications/party/entitydef/entitymodel.xml
>>>
>>>
>>>
>>> This is a great effort, so don't get me wrong, but...
>>>
>>> Most of these seem to contain zero information not already in each
>>> line, or in other words they could be derived through a small method
>>> (like those that exist in the form widget) that adds spaces and
>>> changes capitalization.
>>>
>>> My vote on this would be leave ALL of this sort of description out as
>>> they don't contain information not already there, but they do add
>>> redundancy and complexity to the files.
>>>
>>> Descriptions really should be for explaining non-obvious use and
>>> purposes of elements, and if there isn't anything non-obvious then
>>> there is no need for a description. General information about from/
>>> thru dates, types, etc can be found in the entity overview on
>>> docs.ofbiz.org.
>>>
>>> -David
>>>
>
>