You are viewing a plain text version of this content. The canonical link for it is here.

Posted to dev@lucene.apache.org by Chris Hostetter <ho...@fucit.org> on 2007/02/20 03:25:33 UTC

commited docs vs wiki -- was: Re: [jira] Commented: (LUCENE-805) New Lucene Demo

: Yeah, query-syntax is pretty static, so that would be fine, but I
: sense a slippery slope here.  Scoring is static, too, but I think if
: people want to add to the scoring doc, that would be fine.  Part of
: me feels like it should be all the docs, including the file formats b/
: c we are trying to encourage people to document.  On the other hand,
: some parts of the docs, like the file formats and query-syntax, feel
: more in stone to me and I can see a case that they should only be
: changed through a patch approach so that a committer is reviewing the

i'm with you all the way on that one ... it seems like every day i change
my mind about how important it is to have "official" documentation vs wiki
documentation.

when solr first entered incubation, most of our stuff went in the wiki
just because it seemed like the easiest way to get feedback,
improvements, and copy-editing from the widest audience ... we discussed
migrating docs into subversion once they were more fleshed out, but now
we're looking at migrating more docs from subversion to the wiki then we
are the other direction.

for Lucene-Java i'd be really leary of things like fileformats,
querystynax, and scoring just being wiki pages ... people still ask
questions about the fileformat from lucene 1.4.2, or how scoring worked in
1.2 ... if the only history of thta info was in a wiki where you had to
figure out the right historic version that lined up with your code based
on date stamps of commits (because we'd want to update the doc when hte
change was commited, not when the release was made)

the killer solution to a lot of problems would be a good utility for
slurping the whole wiki into html files, with all of hte wiki links *and*
all of the links from the wiki to the "site" being translated into
relative file paths as an automated part of hte release.

the only other anoyance i have about the wiki that wouldn't be solved with
something like thta is the "javadoc annotation missing feature" problem of
the wiki ... some things really belong in javadocs, but you still want to
allow users to easily annoate those docs with their own tips/tricks about
using it ... stuff that's deliniated as not being formal documentation,
but still good to keep in mind, ie:
   http://wiki.apache.org/solr/AnalyzersTokenizersTokenFilters

PHP.net set the gold standard for this years ago...
   http://www.php.net/manual/en/language.oop5.basic.php

...and Perl's CPAN is making progress...
  http://www.annocpan.org/~AREIBENS/PDF-API2-0.57/lib/PDF/API2.pm#note_1389

... but i've never seen a good Javadoc appraoch to this problem, and none
of these solutions really address the issue of "releasing" baked versions
of hte documentation that include the annotations/tips ... you'd have to
commit them as part of the formal docs)

: wiki policy to notify java-dev or java-commits when there are
: changes?  I'm not sure how the wiki is administered or if I'm missing
: the notifications already.

i believe wiki edits already go to the commits list (that's how we set
Solr up anyway)




-Hoss


---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org

Re: commited docs vs wiki -- was: Re: [jira] Commented: (LUCENE-805) New Lucene Demo

Posted by Doug Cutting <cu...@apache.org>.

Chris Hostetter wrote:
> I kind of glossed over this when Nicolas first sent it -- but it makes
> total sense ... if a redaio button in Jira is legaly binding enough to
> allow someone with a signed CLA to commit into the repository and include
> in a release, then a checkbox on a "web form based document repository"
> (ie: cwiki) should be enough to allow someone with a signed CLA to export
> all the documentaiton and include it in a release.

I don't think the analogy is perfect.  Exporting the wiki would be a 
bulk, automatic process, while applying a patch is a manual and 
incremental.  Part of a committer's duty when considering a patch is to 
determine whether the contributor likely had the right to contribute it. 
  Doing this on a patch-by-patch basis is not so bad: chances are you're 
somewhat familiar with the contributor from the mailing list.  A 
substantial contribution from out-of-nowhere should cause you to raise 
your eyebrows and learn a bit about the contributor before committing 
it.  But doing it on a wholesale export of a wiki is much harder, since 
the wiki is constructed over years by a wide variety of contributors, 
and thus committers might not examine every contribution to the wiki 
they export.

Doug

---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org

Re: commited docs vs wiki -- was: Re: [jira] Commented: (LUCENE-805) New Lucene Demo

Posted by Chris Hostetter <ho...@fucit.org>.

: I will ask on legal-discuss if click-agreement is sufficient.

: > I don't know how confluence works, but maybe it is possible to make
: > a "click-agreement" like the one there is in Jira while submitting
: > patches ?

I kind of glossed over this when Nicolas first sent it -- but it makes
total sense ... if a redaio button in Jira is legaly binding enough to
allow someone with a signed CLA to commit into the repository and include
in a release, then a checkbox on a "web form based document repository"
(ie: cwiki) should be enough to allow someone with a signed CLA to export
all the documentaiton and include it in a release.

we would probably want to have two seperate "web form based document
repository" areas ... one where you can only make edits if you check
the legal box which is archived and included in the releases by a commiter
(ie: socring docs, fileformat docs, tutorials, demos, etc...) and one that
is completley publicly accessible (ie: the FAQ, list of projects using
lucene, list of articles/books about lucene, whiteboard of ideas, tips and
tricks, etc...)



-Hoss


---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org

Re: commited docs vs wiki -- was: Re: [jira] Commented: (LUCENE-805) New Lucene Demo

Posted by Grant Ingersoll <gr...@gmail.com>.

I will ask on legal-discuss if click-agreement is sufficient.

-Grant

On Feb 24, 2007, at 8:13 AM, Nicolas Lalevée wrote:

> Le samedi 24 février 2007 13:52, Grant Ingersoll a écrit :
>> Sigh.
>>
>> On http://cwiki.apache.org/confluence/display/CWIKI/Index
>>
>> Read the FAQ entry titled "But what if we would like the community at
>> large to help maintain the space?"
>> It seems if we want to bundle the docs w/ a release, then we would
>> need a CLA for people that contribute.  At least that is my reading.
>
> I don't know how confluence works, but maybe it is possible to make
> a "click-agreement" like the one there is in Jira while submitting  
> patches ?
>
> Nicolas
>
>>
>> On workaround that I _think_ would be satisfactory, though is to not
>> bundle that documentation, but just host it under our "Site Versions"
>> just like we always do.  Then in the docs we do release, the links
>> would take the user to the appropriate site version.  Then, we
>> wouldn't be bundling the wiki contents.
>>
>> This would take some ANT work to do string replacement on the URLs in
>> those docs.
>>
>> On Feb 24, 2007, at 1:24 AM, Chris Hostetter wrote:
>>> : think we could move more to the Wiki.  One solution, would be to
>>>
>>> have
>>>
>>> : a simple script that calls wget (or some crawler) and downloads  
>>> all
>>> : of the wiki.  It would, however, be better if the wiki supported
>>>
>>> yeah .. that's a fairly crude approach that would result in a lot
>>> of the
>>> useless navigation links being left in place -- and we'd need
>>> soemthing
>>> somewaht custom to deal with changing the site links t opoint to
>>> the local
>>> files
>>>
>>> : tagging a snapshot.  I've seen flashes of references on other
>>> : projects about the Confluence wiki from Atlassian.  Is this
>>>
>>> available
>>>
>>> : for use at Apache and does it have the features we want?
>>>
>>> no idea if it has any features like this ... but it does appear  
>>> to be
>>> available, geronimo and apache laps use it...
>>>
>>> http://cwiki.apache.org/geronimo/
>>> http://cwiki.apache.org/labs/home.html
>>>
>>> ....oooohhhhhhh.... this looks promising...
>>>
>>> http://cwiki.apache.org/confluence/spaces/exportspace.action? 
>>> key=labs
>>>
>>>
>>>
>>>
>>> -Hoss
>>>
>>>
>>> -------------------------------------------------------------------- 
>>> -
>>> To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
>>> For additional commands, e-mail: java-dev-help@lucene.apache.org
>>
>> --------------------------
>> Grant Ingersoll
>> Center for Natural Language Processing
>> http://www.cnlp.org
>>
>> Read the Lucene Java FAQ at http://wiki.apache.org/jakarta-lucene/
>> LuceneFAQ
>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
>> For additional commands, e-mail: java-dev-help@lucene.apache.org
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: java-dev-help@lucene.apache.org
>

------------------------------------------------------
Grant Ingersoll
http://www.grantingersoll.com/
http://lucene.grantingersoll.com
http://www.paperoftheweek.com/



---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org

Re: commited docs vs wiki -- was: Re: [jira] Commented: (LUCENE-805) New Lucene Demo

Posted by Nicolas Lalevée <ni...@anyware-tech.com>.

Le samedi 24 février 2007 13:52, Grant Ingersoll a écrit :
> Sigh.
>
> On http://cwiki.apache.org/confluence/display/CWIKI/Index
>
> Read the FAQ entry titled "But what if we would like the community at
> large to help maintain the space?"
> It seems if we want to bundle the docs w/ a release, then we would
> need a CLA for people that contribute.  At least that is my reading.

I don't know how confluence works, but maybe it is possible to make 
a "click-agreement" like the one there is in Jira while submitting patches ?

Nicolas

>
> On workaround that I _think_ would be satisfactory, though is to not
> bundle that documentation, but just host it under our "Site Versions"
> just like we always do.  Then in the docs we do release, the links
> would take the user to the appropriate site version.  Then, we
> wouldn't be bundling the wiki contents.
>
> This would take some ANT work to do string replacement on the URLs in
> those docs.
>
> On Feb 24, 2007, at 1:24 AM, Chris Hostetter wrote:
> > : think we could move more to the Wiki.  One solution, would be to
> >
> > have
> >
> > : a simple script that calls wget (or some crawler) and downloads all
> > : of the wiki.  It would, however, be better if the wiki supported
> >
> > yeah .. that's a fairly crude approach that would result in a lot
> > of the
> > useless navigation links being left in place -- and we'd need
> > soemthing
> > somewaht custom to deal with changing the site links t opoint to
> > the local
> > files
> >
> > : tagging a snapshot.  I've seen flashes of references on other
> > : projects about the Confluence wiki from Atlassian.  Is this
> >
> > available
> >
> > : for use at Apache and does it have the features we want?
> >
> > no idea if it has any features like this ... but it does appear to be
> > available, geronimo and apache laps use it...
> >
> > http://cwiki.apache.org/geronimo/
> > http://cwiki.apache.org/labs/home.html
> >
> > ....oooohhhhhhh.... this looks promising...
> >
> > http://cwiki.apache.org/confluence/spaces/exportspace.action?key=labs
> >
> >
> >
> >
> > -Hoss
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
> > For additional commands, e-mail: java-dev-help@lucene.apache.org
>
> --------------------------
> Grant Ingersoll
> Center for Natural Language Processing
> http://www.cnlp.org
>
> Read the Lucene Java FAQ at http://wiki.apache.org/jakarta-lucene/
> LuceneFAQ
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
> For additional commands, e-mail: java-dev-help@lucene.apache.org

---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org