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, [EMAIL PROTECTED] 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:[EMAIL PROTECTED]
Sent: Thursday, November 22, 2007 2:00 PM
To: dev@ofbiz.apache.org
Cc: [EMAIL PROTECTED]
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
