You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ofbiz.apache.org by Jacques Le Roux <ja...@les7arts.com> on 2015/10/27 09:12:27 UTC
A rant I could not hold (read: wanted to share)
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
Re: A rant I could not hold (read: wanted to share)
Posted by Sharan Foga <sh...@gmail.com>.
Hi
Thanks for the feedback and I'm glad it's useful. (I'm going through it
myself ! :-) )
I recommended the link because it's something that happens naturally and
before we know it becomes something to big and scary to even think
about. We know that we have some tidying up to do especially around
documentation and now with the recent initiative, the framework and
code, so it's about acknowledging the problem and then going ahead and
doing something about it.
Thanks
Sharan
On 02/05/16 08:41, Taher Alkhateeb wrote:an
> Hi Jacques,
>
> Very useful and interesting. The material seems to be give even more value
> for obsessive compulsive people like me :) Thank you.
>
> Taher Alkhateeb
>
> On Sun, May 1, 2016 at 9:02 PM, Jacques Le Roux <
> jacques.le.roux@les7arts.com> wrote:
>
>> For the moment I'm reading (one page a day :D)
>> http://www.howtomakesenseofanymess.com/ as suggested by Sharan
>>
>> Jacques
>>
>>
>> Le 28/10/2015 � 19:31, Jacques Le Roux a �crit :
>>
>>> That's a good idea to start Gavin! I will try that 1st. I already looked
>>> at their documentation but only cursorily
>>>
>>> Jacques
>>>
>>> Le 27/10/2015 14:02, Gavin Mabie a �crit :
>>>
>>>> Let's bench mark against docs from the competition - like Open Bravo,
>>>> Adempiere etc.
>>>>
>>>> On Tue, Oct 27, 2015 at 2:59 PM, Ron Wheeler <
>>>> rwheeler@artifact-software.com
>>>>
>>>>> wrote:
>>>>> +1
>>>>> As a newcomer, the docs were a big turn-off.
>>>>>
>>>>> Sharan is doing a great job of organizing it.
>>>>> I hope that we can do something with the Framework that makes a cleaner
>>>>> separation between the business application and the plumbing.
>>>>>
>>>>> Ron
>>>>>
>>>>>
>>>>> On 27/10/2015 4: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
>>>>>>
>>>>>>
>>>>>> --
>>>>> Ron Wheeler
>>>>> President
>>>>> Artifact Software Inc
>>>>> email: rwheeler@artifact-software.com
>>>>> skype: ronaldmwheeler
>>>>> phone: 866-970-2435, ext 102
>>>>>
>>>>>
>>>>>
Re: A rant I could not hold (read: wanted to share)
Posted by Taher Alkhateeb <sl...@gmail.com>.
Hi Jacques,
Very useful and interesting. The material seems to be give even more value
for obsessive compulsive people like me :) Thank you.
Taher Alkhateeb
On Sun, May 1, 2016 at 9:02 PM, Jacques Le Roux <
jacques.le.roux@les7arts.com> wrote:
> For the moment I'm reading (one page a day :D)
> http://www.howtomakesenseofanymess.com/ as suggested by Sharan
>
> Jacques
>
>
> Le 28/10/2015 à 19:31, Jacques Le Roux a écrit :
>
>> That's a good idea to start Gavin! I will try that 1st. I already looked
>> at their documentation but only cursorily
>>
>> Jacques
>>
>> Le 27/10/2015 14:02, Gavin Mabie a écrit :
>>
>>> Let's bench mark against docs from the competition - like Open Bravo,
>>> Adempiere etc.
>>>
>>> On Tue, Oct 27, 2015 at 2:59 PM, Ron Wheeler <
>>> rwheeler@artifact-software.com
>>>
>>>> wrote:
>>>> +1
>>>> As a newcomer, the docs were a big turn-off.
>>>>
>>>> Sharan is doing a great job of organizing it.
>>>> I hope that we can do something with the Framework that makes a cleaner
>>>> separation between the business application and the plumbing.
>>>>
>>>> Ron
>>>>
>>>>
>>>> On 27/10/2015 4: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
>>>>>
>>>>>
>>>>> --
>>>> Ron Wheeler
>>>> President
>>>> Artifact Software Inc
>>>> email: rwheeler@artifact-software.com
>>>> skype: ronaldmwheeler
>>>> phone: 866-970-2435, ext 102
>>>>
>>>>
>>>>
>>
>
Re: A rant I could not hold (read: wanted to share)
Posted by Jacques Le Roux <ja...@les7arts.com>.
For the moment I'm reading (one page a day :D) http://www.howtomakesenseofanymess.com/ as suggested by Sharan
Jacques
Le 28/10/2015 � 19:31, Jacques Le Roux a �crit :
> That's a good idea to start Gavin! I will try that 1st. I already looked at their documentation but only cursorily
>
> Jacques
>
> Le 27/10/2015 14:02, Gavin Mabie a �crit :
>> Let's bench mark against docs from the competition - like Open Bravo,
>> Adempiere etc.
>>
>> On Tue, Oct 27, 2015 at 2:59 PM, Ron Wheeler <rwheeler@artifact-software.com
>>> wrote:
>>> +1
>>> As a newcomer, the docs were a big turn-off.
>>>
>>> Sharan is doing a great job of organizing it.
>>> I hope that we can do something with the Framework that makes a cleaner
>>> separation between the business application and the plumbing.
>>>
>>> Ron
>>>
>>>
>>> On 27/10/2015 4: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
>>>>
>>>>
>>> --
>>> Ron Wheeler
>>> President
>>> Artifact Software Inc
>>> email: rwheeler@artifact-software.com
>>> skype: ronaldmwheeler
>>> phone: 866-970-2435, ext 102
>>>
>>>
>
Re: A rant I could not hold (read: wanted to share)
Posted by Jacques Le Roux <ja...@les7arts.com>.
That's a good idea to start Gavin! I will try that 1st. I already looked at their documentation but only cursorily
Jacques
Le 27/10/2015 14:02, Gavin Mabie a écrit :
> Let's bench mark against docs from the competition - like Open Bravo,
> Adempiere etc.
>
> On Tue, Oct 27, 2015 at 2:59 PM, Ron Wheeler <rwheeler@artifact-software.com
>> wrote:
>> +1
>> As a newcomer, the docs were a big turn-off.
>>
>> Sharan is doing a great job of organizing it.
>> I hope that we can do something with the Framework that makes a cleaner
>> separation between the business application and the plumbing.
>>
>> Ron
>>
>>
>> On 27/10/2015 4: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
>>>
>>>
>> --
>> Ron Wheeler
>> President
>> Artifact Software Inc
>> email: rwheeler@artifact-software.com
>> skype: ronaldmwheeler
>> phone: 866-970-2435, ext 102
>>
>>
Re: A rant I could not hold (read: wanted to share)
Posted by Gavin Mabie <kw...@gmail.com>.
Let's bench mark against docs from the competition - like Open Bravo,
Adempiere etc.
On Tue, Oct 27, 2015 at 2:59 PM, Ron Wheeler <rwheeler@artifact-software.com
> wrote:
> +1
> As a newcomer, the docs were a big turn-off.
>
> Sharan is doing a great job of organizing it.
> I hope that we can do something with the Framework that makes a cleaner
> separation between the business application and the plumbing.
>
> Ron
>
>
> On 27/10/2015 4: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
>>
>>
>
> --
> Ron Wheeler
> President
> Artifact Software Inc
> email: rwheeler@artifact-software.com
> skype: ronaldmwheeler
> phone: 866-970-2435, ext 102
>
>
Re: A rant I could not hold (read: wanted to share)
Posted by Ron Wheeler <rw...@artifact-software.com>.
+1
As a newcomer, the docs were a big turn-off.
Sharan is doing a great job of organizing it.
I hope that we can do something with the Framework that makes a cleaner
separation between the business application and the plumbing.
Ron
On 27/10/2015 4: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
>
--
Ron Wheeler
President
Artifact Software Inc
email: rwheeler@artifact-software.com
skype: ronaldmwheeler
phone: 866-970-2435, ext 102
Re: A rant I could not hold (read: wanted to share)
Posted by Gavin Mabie <kw...@gmail.com>.
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.crum@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
>>
>
Re: A rant I could not hold (read: wanted to share)
Posted by Jacques Le Roux <ja...@les7arts.com>.
Le 27/10/2015 16:23, Ron Wheeler a écrit :
> On 10/27/2015 1:12 AM, Jacques Le Roux wrote:
>>> 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? ;-)
As ever, it's up to the volunteers... :)
Jacques
Re: A rant I could not hold (read: wanted to share)
Posted by Ron Wheeler <rw...@artifact-software.com>.
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: rwheeler@artifact-software.com
skype: ronaldmwheeler
phone: 866-970-2435, ext 102
Re: A rant I could not hold (read: wanted to share)
Posted by Adrian Crum <ad...@sandglass-software.com>.
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