Have a README.TXT file in release package

[Jacques Le Roux]

Hi,

We often get questions from people not reading the basic documentation. Like not able to run Gradle because ignoring init-gradle-wrapper scripts.

I know there will always people not reading the documentation. But maybe, to prevent most obvious questions and tempting RTFM answers, we could add a
small README.TXT with basic information in OFBiz root.

It would ultimately refer to README.adoc. Also saying that README.adoc can be read with a text reader tool. And it's easy to follow
https://asciidoctor.org/docs/convert-documents/#converting-a-document-to-html

What do you think?

Jacques

[deepak nigam-2]

+1

Thanks & Regards
--
Deepak Nigam



On Sun, May 10, 2020, 10:15 PM Jacques Le Roux <[hidden email]>
wrote:

> Hi,
>
> We often get questions from people not reading the basic documentation.
> Like not able to run Gradle because ignoring init-gradle-wrapper scripts.
>
> I know there will always people not reading the documentation. But maybe,
> to prevent most obvious questions and tempting RTFM answers, we could add a
> small README.TXT with basic information in OFBiz root.
>
> It would ultimately refer to README.adoc. Also saying that README.adoc can
> be read with a text reader tool. And it's easy to follow
>
> https://asciidoctor.org/docs/convert-documents/#converting-a-document-to-html
>
> What do you think?
>
> Jacques
>
>

[Michael Brohl-3]

Hi Jacques,

do you think that people who do not read README.adoc would rather read a
README.txt file?

I doubt that you'll reach those people with that file but it might be
worth a try. I would name the file README without extension to better
match LICENSE, NOTICE, VERSION etc..

Thanks,

Michael Brohl

ecomify GmbH - www.ecomify.de


Am 10.05.20 um 18:43 schrieb Jacques Le Roux:

> Hi,
>
> We often get questions from people not reading the basic
> documentation. Like not able to run Gradle because ignoring
> init-gradle-wrapper scripts.
>
> I know there will always people not reading the documentation. But
> maybe, to prevent most obvious questions and tempting RTFM answers, we
> could add a small README.TXT with basic information in OFBiz root.
>
> It would ultimately refer to README.adoc. Also saying that README.adoc
> can be read with a text reader tool. And it's easy to follow
> https://asciidoctor.org/docs/convert-documents/#converting-a-document-to-html
>
> What do you think?
>
> Jacques
>

[Pierre Smits-3]

Call it INSTALLATION, and simply highlight what is necessary to get OFBiz
running:
Have jdk, version 8
invoke the gradle-init script

I concur with Michael, people who don't read the readme.adoc will possibly
forgo the other readme too.

Met vriendelijke groet,

Pierre Smits
*Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/> since
2008 (without privileges)

*Apache Trafodion <https://trafodion.apache.org>, Vice President*
*Apache Directory <https://directory.apache.org>, PMC Member*
Apache Incubator <https://incubator.apache.org>, committer
Apache Steve <https://steve.apache.org>, committer


On Sun, May 10, 2020 at 7:29 PM Michael Brohl <[hidden email]>
wrote:

> Hi Jacques,
>
> do you think that people who do not read README.adoc would rather read a
> README.txt file?
>
> I doubt that you'll reach those people with that file but it might be
> worth a try. I would name the file README without extension to better
> match LICENSE, NOTICE, VERSION etc..
>
> Thanks,
>
> Michael Brohl
>
> ecomify GmbH - www.ecomify.de
>
>
> Am 10.05.20 um 18:43 schrieb Jacques Le Roux:
> > Hi,
> >
> > We often get questions from people not reading the basic
> > documentation. Like not able to run Gradle because ignoring
> > init-gradle-wrapper scripts.
> >
> > I know there will always people not reading the documentation. But
> > maybe, to prevent most obvious questions and tempting RTFM answers, we
> > could add a small README.TXT with basic information in OFBiz root.
> >
> > It would ultimately refer to README.adoc. Also saying that README.adoc
> > can be read with a text reader tool. And it's easy to follow
> >
> https://asciidoctor.org/docs/convert-documents/#converting-a-document-to-html
> >
> > What do you think?
> >
> > Jacques
> >
>
>

[Taher Alkhateeb-2]

If I see two README files in a project, I would get confused. Conventions are usually that there is only one README, one LICENSE, one INSTALL and so on ...

Perhaps another approach is to slimdown the README file and refer to other documentation using links to the other resources. This way you can emphasize any point you want in the main README and leave the other less used documentation for elsewhere.


On Sunday, May 10, 2020 19:43 +03, Jacques Le Roux <[hidden email]> wrote:
 Hi,

We often get questions from people not reading the basic documentation. Like not able to run Gradle because ignoring init-gradle-wrapper scripts.

I know there will always people not reading the documentation. But maybe, to prevent most obvious questions and tempting RTFM answers, we could add a
small README.TXT with basic information in OFBiz root.

It would ultimately refer to README.adoc. Also saying that README.adoc can be read with a text reader tool. And it's easy to follow
https://asciidoctor.org/docs/convert-documents/#converting-a-document-to-html

What do you think?

Jacques
 
 

[Jacques Le Roux]

Thank you All for your answers,

I like the idea of creating a simple INSTALL file with minimum installation information and redirection to more documentation

I created https://issues.apache.org/jira/browse/OFBIZ-11691 for that

Jacques

Le 10/05/2020 à 18:43, Jacques Le Roux a écrit :

> Hi,
>
> We often get questions from people not reading the basic documentation. Like not able to run Gradle because ignoring init-gradle-wrapper scripts.
>
> I know there will always people not reading the documentation. But maybe, to prevent most obvious questions and tempting RTFM answers, we could add
> a small README.TXT with basic information in OFBiz root.
>
> It would ultimately refer to README.adoc. Also saying that README.adoc can be read with a text reader tool. And it's easy to follow
> https://asciidoctor.org/docs/convert-documents/#converting-a-document-to-html
>
> What do you think?
>
> Jacques
>

[Jacques Le Roux]

Hi,

I committed an INSTALL file in trunk main dir, please review and amend if necessary

Thanks

Jacques

Le 11/05/2020 à 12:08, Jacques Le Roux a écrit :

> Thank you All for your answers,
>
> I like the idea of creating a simple INSTALL file with minimum installation information and redirection to more documentation
>
> I created https://issues.apache.org/jira/browse/OFBIZ-11691 for that
>
> Jacques
>
> Le 10/05/2020 à 18:43, Jacques Le Roux a écrit :
>> Hi,
>>
>> We often get questions from people not reading the basic documentation. Like not able to run Gradle because ignoring init-gradle-wrapper scripts.
>>
>> I know there will always people not reading the documentation. But maybe, to prevent most obvious questions and tempting RTFM answers, we could add
>> a small README.TXT with basic information in OFBiz root.
>>
>> It would ultimately refer to README.adoc. Also saying that README.adoc can be read with a text reader tool. And it's easy to follow
>> https://asciidoctor.org/docs/convert-documents/#converting-a-document-to-html
>>
>> What do you think?
>>
>> Jacques
>>

[Pierre Smits-3]

Thanks Jacques,

By the way, why can't both init-gradle-wrapper.sh
<https://github.com/apache/ofbiz-framework/blob/trunk/gradle/init-gradle-wrapper.sh>
 and init-gradle-wrapper.bat
<https://github.com/apache/ofbiz-framework/blob/trunk/init-gradle-wrapper.bat>
be
in the same location? Both do the same thing, but for different OSes

Met vriendelijke groet,

Pierre Smits
*Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/> since
2008 (without privileges)

*Apache Trafodion <https://trafodion.apache.org>, Vice President*
*Apache Directory <https://directory.apache.org>, PMC Member*
Apache Incubator <https://incubator.apache.org>, committer
Apache Steve <https://steve.apache.org>, committer


On Thu, May 14, 2020 at 6:51 PM Jacques Le Roux <
[hidden email]> wrote:

> Hi,
>
> I committed an INSTALL file in trunk main dir, please review and amend if
> necessary
>
> Thanks
>
> Jacques
>
> Le 11/05/2020 à 12:08, Jacques Le Roux a écrit :
> > Thank you All for your answers,
> >
> > I like the idea of creating a simple INSTALL file with minimum
> installation information and redirection to more documentation
> >
> > I created https://issues.apache.org/jira/browse/OFBIZ-11691 for that
> >
> > Jacques
> >
> > Le 10/05/2020 à 18:43, Jacques Le Roux a écrit :
> >> Hi,
> >>
> >> We often get questions from people not reading the basic documentation.
> Like not able to run Gradle because ignoring init-gradle-wrapper scripts.
> >>
> >> I know there will always people not reading the documentation. But
> maybe, to prevent most obvious questions and tempting RTFM answers, we
> could add
> >> a small README.TXT with basic information in OFBiz root.
> >>
> >> It would ultimately refer to README.adoc. Also saying that README.adoc
> can be read with a text reader tool. And it's easy to follow
> >>
> https://asciidoctor.org/docs/convert-documents/#converting-a-document-to-html
> >>
> >> What do you think?
> >>
> >> Jacques
> >>
>

[Jacques Le Roux]

Yes why not put init-gradle-wrapper.sh in main dir? The most simple way :)

I know we had this discussion before...

Jacques

Le 14/05/2020 à 19:04, Pierre Smits a écrit :

> Thanks Jacques,
>
> By the way, why can't both init-gradle-wrapper.sh
> <https://github.com/apache/ofbiz-framework/blob/trunk/gradle/init-gradle-wrapper.sh>
>   and init-gradle-wrapper.bat
> <https://github.com/apache/ofbiz-framework/blob/trunk/init-gradle-wrapper.bat>
> be
> in the same location? Both do the same thing, but for different OSes
>
> Met vriendelijke groet,
>
> Pierre Smits
> *Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/> since
> 2008 (without privileges)
>
> *Apache Trafodion <https://trafodion.apache.org>, Vice President*
> *Apache Directory <https://directory.apache.org>, PMC Member*
> Apache Incubator <https://incubator.apache.org>, committer
> Apache Steve <https://steve.apache.org>, committer
>
>
> On Thu, May 14, 2020 at 6:51 PM Jacques Le Roux <
> [hidden email]> wrote:
>
>> Hi,
>>
>> I committed an INSTALL file in trunk main dir, please review and amend if
>> necessary
>>
>> Thanks
>>
>> Jacques
>>
>> Le 11/05/2020 à 12:08, Jacques Le Roux a écrit :
>>> Thank you All for your answers,
>>>
>>> I like the idea of creating a simple INSTALL file with minimum
>> installation information and redirection to more documentation
>>> I created https://issues.apache.org/jira/browse/OFBIZ-11691 for that
>>>
>>> Jacques
>>>
>>> Le 10/05/2020 à 18:43, Jacques Le Roux a écrit :
>>>> Hi,
>>>>
>>>> We often get questions from people not reading the basic documentation.
>> Like not able to run Gradle because ignoring init-gradle-wrapper scripts.
>>>> I know there will always people not reading the documentation. But
>> maybe, to prevent most obvious questions and tempting RTFM answers, we
>> could add
>>>> a small README.TXT with basic information in OFBiz root.
>>>>
>>>> It would ultimately refer to README.adoc. Also saying that README.adoc
>> can be read with a text reader tool. And it's easy to follow
>> https://asciidoctor.org/docs/convert-documents/#converting-a-document-to-html
>>>> What do you think?
>>>>
>>>> Jacques
>>>>

[Pierre Smits-3]

Indeed.

And while add it, why not just call the two files 'init-gradle'?

Met vriendelijke groet,

Pierre Smits
*Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/> since
2008 (without privileges)

*Apache Trafodion <https://trafodion.apache.org>, Vice President*
*Apache Directory <https://directory.apache.org>, PMC Member*
Apache Incubator <https://incubator.apache.org>, committer
Apache Steve <https://steve.apache.org>, committer


On Thu, May 14, 2020 at 7:31 PM Jacques Le Roux <
[hidden email]> wrote:

> Yes why not put init-gradle-wrapper.sh in main dir? The most simple way :)
>
> I know we had this discussion before...
>
> Jacques
>
> Le 14/05/2020 à 19:04, Pierre Smits a écrit :
> > Thanks Jacques,
> >
> > By the way, why can't both init-gradle-wrapper.sh
> > <
> https://github.com/apache/ofbiz-framework/blob/trunk/gradle/init-gradle-wrapper.sh
> >
> >   and init-gradle-wrapper.bat
> > <
> https://github.com/apache/ofbiz-framework/blob/trunk/init-gradle-wrapper.bat
> >
> > be
> > in the same location? Both do the same thing, but for different OSes
> >
> > Met vriendelijke groet,
> >
> > Pierre Smits
> > *Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/>
> since
> > 2008 (without privileges)
> >
> > *Apache Trafodion <https://trafodion.apache.org>, Vice President*
> > *Apache Directory <https://directory.apache.org>, PMC Member*
> > Apache Incubator <https://incubator.apache.org>, committer
> > Apache Steve <https://steve.apache.org>, committer
> >
> >
> > On Thu, May 14, 2020 at 6:51 PM Jacques Le Roux <
> > [hidden email]> wrote:
> >
> >> Hi,
> >>
> >> I committed an INSTALL file in trunk main dir, please review and amend
> if
> >> necessary
> >>
> >> Thanks
> >>
> >> Jacques
> >>
> >> Le 11/05/2020 à 12:08, Jacques Le Roux a écrit :
> >>> Thank you All for your answers,
> >>>
> >>> I like the idea of creating a simple INSTALL file with minimum
> >> installation information and redirection to more documentation
> >>> I created https://issues.apache.org/jira/browse/OFBIZ-11691 for that
> >>>
> >>> Jacques
> >>>
> >>> Le 10/05/2020 à 18:43, Jacques Le Roux a écrit :
> >>>> Hi,
> >>>>
> >>>> We often get questions from people not reading the basic
> documentation.
> >> Like not able to run Gradle because ignoring init-gradle-wrapper
> scripts.
> >>>> I know there will always people not reading the documentation. But
> >> maybe, to prevent most obvious questions and tempting RTFM answers, we
> >> could add
> >>>> a small README.TXT with basic information in OFBiz root.
> >>>>
> >>>> It would ultimately refer to README.adoc. Also saying that README.adoc
> >> can be read with a text reader tool. And it's easy to follow
> >>
> https://asciidoctor.org/docs/convert-documents/#converting-a-document-to-html
> >>>> What do you think?
> >>>>
> >>>> Jacques
> >>>>
>

[Jacques Le Roux]

Hi Pierre, All,

I have backported the new INSTALL file in R17 and R18 and closed OFBIZ-11691

Pierre, I suggest you create a Jira for your propositions below. Because moving these scripts has implication in their content (code)

Thanks

Jacques

Le 14/05/2020 à 19:53, Pierre Smits a écrit :

> Indeed.
>
> And while add it, why not just call the two files 'init-gradle'?
>
> Met vriendelijke groet,
>
> Pierre Smits
> *Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/> since
> 2008 (without privileges)
>
> *Apache Trafodion <https://trafodion.apache.org>, Vice President*
> *Apache Directory <https://directory.apache.org>, PMC Member*
> Apache Incubator <https://incubator.apache.org>, committer
> Apache Steve <https://steve.apache.org>, committer
>
>
> On Thu, May 14, 2020 at 7:31 PM Jacques Le Roux <
> [hidden email]> wrote:
>
>> Yes why not put init-gradle-wrapper.sh in main dir? The most simple way :)
>>
>> I know we had this discussion before...
>>
>> Jacques
>>
>> Le 14/05/2020 à 19:04, Pierre Smits a écrit :
>>> Thanks Jacques,
>>>
>>> By the way, why can't both init-gradle-wrapper.sh
>>> <
>> https://github.com/apache/ofbiz-framework/blob/trunk/gradle/init-gradle-wrapper.sh
>>>    and init-gradle-wrapper.bat
>>> <
>> https://github.com/apache/ofbiz-framework/blob/trunk/init-gradle-wrapper.bat
>>> be
>>> in the same location? Both do the same thing, but for different OSes
>>>
>>> Met vriendelijke groet,
>>>
>>> Pierre Smits
>>> *Proud* *contributor** of* Apache OFBiz <https://ofbiz.apache.org/>
>> since
>>> 2008 (without privileges)
>>>
>>> *Apache Trafodion <https://trafodion.apache.org>, Vice President*
>>> *Apache Directory <https://directory.apache.org>, PMC Member*
>>> Apache Incubator <https://incubator.apache.org>, committer
>>> Apache Steve <https://steve.apache.org>, committer
>>>
>>>
>>> On Thu, May 14, 2020 at 6:51 PM Jacques Le Roux <
>>> [hidden email]> wrote:
>>>
>>>> Hi,
>>>>
>>>> I committed an INSTALL file in trunk main dir, please review and amend
>> if
>>>> necessary
>>>>
>>>> Thanks
>>>>
>>>> Jacques
>>>>
>>>> Le 11/05/2020 à 12:08, Jacques Le Roux a écrit :
>>>>> Thank you All for your answers,
>>>>>
>>>>> I like the idea of creating a simple INSTALL file with minimum
>>>> installation information and redirection to more documentation
>>>>> I created https://issues.apache.org/jira/browse/OFBIZ-11691 for that
>>>>>
>>>>> Jacques
>>>>>
>>>>> Le 10/05/2020 à 18:43, Jacques Le Roux a écrit :
>>>>>> Hi,
>>>>>>
>>>>>> We often get questions from people not reading the basic
>> documentation.
>>>> Like not able to run Gradle because ignoring init-gradle-wrapper
>> scripts.
>>>>>> I know there will always people not reading the documentation. But
>>>> maybe, to prevent most obvious questions and tempting RTFM answers, we
>>>> could add
>>>>>> a small README.TXT with basic information in OFBiz root.
>>>>>>
>>>>>> It would ultimately refer to README.adoc. Also saying that README.adoc
>>>> can be read with a text reader tool. And it's easy to follow
>>>>
>> https://asciidoctor.org/docs/convert-documents/#converting-a-document-to-html
>>>>>> What do you think?
>>>>>>
>>>>>> Jacques
>>>>>>