Mailing List Archive

should we clean up dev-docs?
I was poking around looking for info on how we release Lucene, and I
stumbled into this dev-docs folder. It seems to have info that's
mostly useful for solr workflows, assumes you are working in
lucene-solr repo, etc. The info about pmc-chair seems helpful, and
maybe Putnam's guide to using git worktree, which was new to me, but
the rest should probably go / get updated to refer to lucene repo.

One question I have is about this adoc format - is it processed by
something and published somewhere, or is this just intended to be read
in the source tree (or maybe on github). If it's the latter, maybe we
should switch to markdown?

Also, I did find the dev-tools folder and the release wizard. The
README.md in there is very helpful. I wonder if we ought to simply
consolidate the docs in dev-docs in here so they are easier to
discover together?

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org
Re: should we clean up dev-docs? [ In reply to ]
I suspect that the adoc format got used because it was the format that was
already being used for the Solr ref guide. +1 to move to Markdown.



On Fri, Oct 15, 2021 at 3:49 PM Michael Sokolov <msokolov@gmail.com> wrote:

> I was poking around looking for info on how we release Lucene, and I
> stumbled into this dev-docs folder. It seems to have info that's
> mostly useful for solr workflows, assumes you are working in
> lucene-solr repo, etc. The info about pmc-chair seems helpful, and
> maybe Putnam's guide to using git worktree, which was new to me, but
> the rest should probably go / get updated to refer to lucene repo.
>
> One question I have is about this adoc format - is it processed by
> something and published somewhere, or is this just intended to be read
> in the source tree (or maybe on github). If it's the latter, maybe we
> should switch to markdown?
>
> Also, I did find the dev-tools folder and the release wizard. The
> README.md in there is very helpful. I wonder if we ought to simply
> consolidate the docs in dev-docs in here so they are easier to
> discover together?
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: dev-help@lucene.apache.org
>
>

--
Adrien
Re: should we clean up dev-docs? [ In reply to ]
A cleanup is needed. One dev-docs folder is enough now :)
We also have the help/ folder which is plaintext since it can be invoked with ./gradlew helpXXX. Someone should decide what goes in help/ vs dev-docs/

Asciidoc is more capable than MD, and renders well in GitHub as well: https://github.com/apache/lucene/blob/main/dev-docs/pmc-chair.adoc
I think there may be some future idea to compile dev-docs into some dev guide online, if so, adoc will make it much easier to cross-link, add images, tables etc.

Jan

> 15. okt. 2021 kl. 16:51 skrev Adrien Grand <jpountz@gmail.com>:
>
> I suspect that the adoc format got used because it was the format that was already being used for the Solr ref guide. +1 to move to Markdown.
>
>
>
> On Fri, Oct 15, 2021 at 3:49 PM Michael Sokolov <msokolov@gmail.com <mailto:msokolov@gmail.com>> wrote:
> I was poking around looking for info on how we release Lucene, and I
> stumbled into this dev-docs folder. It seems to have info that's
> mostly useful for solr workflows, assumes you are working in
> lucene-solr repo, etc. The info about pmc-chair seems helpful, and
> maybe Putnam's guide to using git worktree, which was new to me, but
> the rest should probably go / get updated to refer to lucene repo.
>
> One question I have is about this adoc format - is it processed by
> something and published somewhere, or is this just intended to be read
> in the source tree (or maybe on github). If it's the latter, maybe we
> should switch to markdown?
>
> Also, I did find the dev-tools folder and the release wizard. The
> README.md in there is very helpful. I wonder if we ought to simply
> consolidate the docs in dev-docs in here so they are easier to
> discover together?
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org <mailto:dev-unsubscribe@lucene.apache.org>
> For additional commands, e-mail: dev-help@lucene.apache.org <mailto:dev-help@lucene.apache.org>
>
>
>
> --
> Adrien
Re: should we clean up dev-docs? [ In reply to ]
> We also have the help/ folder which is plaintext since it can be invoked with ./gradlew helpXXX. Someone should decide what goes in help/ vs dev-docs/

In all honesty, I prefer plain text files, much in the spirit of RFC
documents. They work well, they display well on all known terminals
and they don't require any added knowledge of N different flavors of
markup formatting languages. I know some of you may disagree but it's
not going to change my mind on the subject - sorry for being
old-fashioned.

D.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org
Re: should we clean up dev-docs? [ In reply to ]
But that's not the situation, instead we have different files in all the
different markup languages already. Dawids is just another.

Please kill the asciidoc right now, so that we have one less.

On Fri, Oct 15, 2021, 4:28 PM Dawid Weiss <dawid.weiss@gmail.com> wrote:

> > We also have the help/ folder which is plaintext since it can be invoked
> with ./gradlew helpXXX. Someone should decide what goes in help/ vs
> dev-docs/
>
> In all honesty, I prefer plain text files, much in the spirit of RFC
> documents. They work well, they display well on all known terminals
> and they don't require any added knowledge of N different flavors of
> markup formatting languages. I know some of you may disagree but it's
> not going to change my mind on the subject - sorry for being
> old-fashioned.
>
> D.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: dev-help@lucene.apache.org
>
>
Re: should we clean up dev-docs? [ In reply to ]
LOL religious wars!

Until we can agree on what markup language (or none at all -- it has a nice
appeal! -- I am old fashioned too!), maybe we could start simply by just
removing the stale docs? We don't need agreement on markup language yet to
do that? Baby steps, progress not perfection.

Mike McCandless

http://blog.mikemccandless.com


On Sat, Oct 16, 2021 at 5:37 AM Robert Muir <rcmuir@gmail.com> wrote:

> But that's not the situation, instead we have different files in all the
> different markup languages already. Dawids is just another.
>
> Please kill the asciidoc right now, so that we have one less.
>
> On Fri, Oct 15, 2021, 4:28 PM Dawid Weiss <dawid.weiss@gmail.com> wrote:
>
>> > We also have the help/ folder which is plaintext since it can be
>> invoked with ./gradlew helpXXX. Someone should decide what goes in help/ vs
>> dev-docs/
>>
>> In all honesty, I prefer plain text files, much in the spirit of RFC
>> documents. They work well, they display well on all known terminals
>> and they don't require any added knowledge of N different flavors of
>> markup formatting languages. I know some of you may disagree but it's
>> not going to change my mind on the subject - sorry for being
>> old-fashioned.
>>
>> D.
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
>> For additional commands, e-mail: dev-help@lucene.apache.org
>>
>>
Re: should we clean up dev-docs? [ In reply to ]
Hi Mike,

> should we clean up dev-docs
+1

I remember we have a project Wiki that is hosted on the Apache domain.
I think this might fit to casually share code-independent information
(operation guide/tips/memorundom) without making commits on the git
repository. What about considering moving the information you see
useful to there, and simply remove /dev-docs (for now)?
https://cwiki.apache.org/confluence/display/LUCENE/Home

> I wonder if we ought to simply consolidate the docs in dev-docs in here so they are easier to discover together?

We could start from the Confluence pages (I'm not sure how many people
use this, but at least it's official space and there is no worry about
file formatting). ?

Tomoko

2021?10?16?(?) 18:58 Michael McCandless <lucene@mikemccandless.com>:
>
> LOL religious wars!
>
> Until we can agree on what markup language (or none at all -- it has a nice appeal! -- I am old fashioned too!), maybe we could start simply by just removing the stale docs? We don't need agreement on markup language yet to do that? Baby steps, progress not perfection.
>
> Mike McCandless
>
> http://blog.mikemccandless.com
>
>
> On Sat, Oct 16, 2021 at 5:37 AM Robert Muir <rcmuir@gmail.com> wrote:
>>
>> But that's not the situation, instead we have different files in all the different markup languages already. Dawids is just another.
>>
>> Please kill the asciidoc right now, so that we have one less.
>>
>> On Fri, Oct 15, 2021, 4:28 PM Dawid Weiss <dawid.weiss@gmail.com> wrote:
>>>
>>> > We also have the help/ folder which is plaintext since it can be invoked with ./gradlew helpXXX. Someone should decide what goes in help/ vs dev-docs/
>>>
>>> In all honesty, I prefer plain text files, much in the spirit of RFC
>>> documents. They work well, they display well on all known terminals
>>> and they don't require any added knowledge of N different flavors of
>>> markup formatting languages. I know some of you may disagree but it's
>>> not going to change my mind on the subject - sorry for being
>>> old-fashioned.
>>>
>>> D.
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
>>> For additional commands, e-mail: dev-help@lucene.apache.org
>>>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org
Re: should we clean up dev-docs? [ In reply to ]
Unrelated to religious fights: for the end user documentation as shipped in the Javadocs we use Markdown and we already have a converter in the Gradle build that for example builds the overview page with all modules and links to system requirements,... It uses flexmark: https://github.com/apache/lucene/blob/main/gradle/documentation/markdown.gradle

How about just integration of dev docs into the general documentation. It might also be useful to anybody just reading our docs on how to contribute.

For the help in Gradle, we can just tell the fkexdown library that's in use to output plain text (see https://github.com/vsch/flexmark-java/issues/63) so "gradlew testHelp" or similar shows it in console friendly way.

In GitHub any format is rendered automatically, so I don't care.

Uwe

Am 16. Oktober 2021 09:57:20 UTC schrieb Michael McCandless <lucene@mikemccandless.com>:
>LOL religious wars!
>
>Until we can agree on what markup language (or none at all -- it has a nice
>appeal! -- I am old fashioned too!), maybe we could start simply by just
>removing the stale docs? We don't need agreement on markup language yet to
>do that? Baby steps, progress not perfection.
>
>Mike McCandless
>
>http://blog.mikemccandless.com
>
>
>On Sat, Oct 16, 2021 at 5:37 AM Robert Muir <rcmuir@gmail.com> wrote:
>
>> But that's not the situation, instead we have different files in all the
>> different markup languages already. Dawids is just another.
>>
>> Please kill the asciidoc right now, so that we have one less.
>>
>> On Fri, Oct 15, 2021, 4:28 PM Dawid Weiss <dawid.weiss@gmail.com> wrote:
>>
>>> > We also have the help/ folder which is plaintext since it can be
>>> invoked with ./gradlew helpXXX. Someone should decide what goes in help/ vs
>>> dev-docs/
>>>
>>> In all honesty, I prefer plain text files, much in the spirit of RFC
>>> documents. They work well, they display well on all known terminals
>>> and they don't require any added knowledge of N different flavors of
>>> markup formatting languages. I know some of you may disagree but it's
>>> not going to change my mind on the subject - sorry for being
>>> old-fashioned.
>>>
>>> D.
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
>>> For additional commands, e-mail: dev-help@lucene.apache.org
>>>
>>>

--
Uwe Schindler
Achterdiek 19, 28357 Bremen
https://www.thetaphi.de