On 27/10/2015 10:25 AM, Adrian Crum wrote:
Building out the documentation in the XSDs would be a huge step in the
right direction.
Adrian Crum
Sandglass Software
www.sandglass-software.com
On 10/27/2015 1:12 AM, Jacques Le Roux wrote:
Hi All,
Don't take this too seriously, it's only a thought that crossed my mind
while reading this snippet at https://db.apache.org/newproject.html
<<Well-documented products tend to build stronger communities than
products that rely [on] source code and JavaDocs alone.>>
And it's is too long for a Tweet :)
I know the OFBiz scope is very large, we are not focused on a topic like
the DB project. So I believe it's harder to well organise our
documentation, or rather, like the project, its scope is large (and
sometimes confusing with not clear borders between topics)
Do I hear a call for sub-projects with more direct ownership of
/responsibility for topics? ;-)
But I think we also rely too much on examples in code. And documentation
in XSDs is not enough (a contrario, see the excellent work by Adrian at
https://cwiki.apache.org/confluence/display/OFBADMIN/Mini+Language+-+minilang+-+simple-method+-+Reference)
because this ways (code including properties files, JavaDocs, XSDs) we
don't cover the business cases and other aspects. In other simpler
words, it's not holistic!
I know, I do that myself everyday, and for a long time. I also believe
the way I approach code in a new area in OFBiz (there are much) is often
by analogy. To be frank in some case it's even kinda Cargo Cult (don't
get me wrong I have nothing against real Cargo Cult ;))
https://en.wikipedia.org/wiki/Cargo_cult
https://www.google.com/search?q=Cargo+Cult&newwindow=1&source=lnms&tbm=isch&sa=X&ved=0CAcQ_AUoAWoVChMIpOyj7ZbiyAIVgtQaCh1KygbV&biw=2144&bih=839&dpr=0.9
The documentation in wiki has improved so far. But, as the DB project
well stresses, if we could improve it more the OFBiz project would be
taken more seriously and we would get more attention. I will try to get
into this direction in the near future...
Thanks for your attention so far :)
Jacques
--
Ron Wheeler
President
Artifact Software Inc
email: rwhee...@artifact-software.com
skype: ronaldmwheeler
phone: 866-970-2435, ext 102
