Building docs in the XSDs would indeed be great - but from the technical user's perspective only. Documentation should ideally recognise the existence of different kinds of audiences.
On Tue, Oct 27, 2015 at 4:25 PM, Adrian Crum < adrian.c...@sandglass-software.com> 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) >> >> 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 >> >
