[jira] Created: (LUCENE-664) [PATCH] small fixes to the new scoring.html doc

classic Classic list List threaded Threaded
41 messages Options
123
Reply | Threaded
Open this post in threaded view
|

[jira] Created: (LUCENE-664) [PATCH] small fixes to the new scoring.html doc

Sebastian Nagel (Jira)
[PATCH] small fixes to the new scoring.html doc
-----------------------------------------------

                 Key: LUCENE-664
                 URL: http://issues.apache.org/jira/browse/LUCENE-664
             Project: Lucene - Java
          Issue Type: Improvement
          Components: Website
    Affects Versions: 2.0.1
            Reporter: Michael McCandless
         Attachments: scoring-small-fixes.patch

This is an awesome initiative.  We need more docs that cleanly explain the inner workings of Lucene in general... thanks Grant & Steve & others!

I have a few small initial proposed fixes, largely just adding some more description around the components of the formula.  But also a couple typos, another link out to Wikipedia, a missing closing ), etc.  I've only made it through the "Understanding the Scoring Formula" section so far.

--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira

       

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

[jira] Commented: (LUCENE-664) [PATCH] small fixes to the new scoring.html doc

Sebastian Nagel (Jira)
    [ http://issues.apache.org/jira/browse/LUCENE-664?page=comments#action_12430051 ]
           
Grant Ingersoll commented on LUCENE-664:
----------------------------------------

Thanks, Michael.  I have applied the patch in scoring-small-fixes.patch and will update the docs.

I will leave this Issue open so that you and others can add patches w/o opening a new Issue for every patch, at least until this document becomes "official".

> [PATCH] small fixes to the new scoring.html doc
> -----------------------------------------------
>
>                 Key: LUCENE-664
>                 URL: http://issues.apache.org/jira/browse/LUCENE-664
>             Project: Lucene - Java
>          Issue Type: Improvement
>          Components: Website
>    Affects Versions: 2.0.1
>            Reporter: Michael McCandless
>         Attachments: scoring-small-fixes.patch
>
>
> This is an awesome initiative.  We need more docs that cleanly explain the inner workings of Lucene in general... thanks Grant & Steve & others!
> I have a few small initial proposed fixes, largely just adding some more description around the components of the formula.  But also a couple typos, another link out to Wikipedia, a missing closing ), etc.  I've only made it through the "Understanding the Scoring Formula" section so far.

--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira

       

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

[jira] Updated: (LUCENE-664) [PATCH] small fixes to the new scoring.html doc

Sebastian Nagel (Jira)
In reply to this post by Sebastian Nagel (Jira)
     [ http://issues.apache.org/jira/browse/LUCENE-664?page=all ]

Karl Wettin updated LUCENE-664:
-------------------------------

    Attachment: lucene.uxf

This is the class diagram (in UMLet format) linked to in the document. It does not explain scoring that much - more of an abstract overview of Lucene than anything else. I might find some time to sequence up the comments.

> [PATCH] small fixes to the new scoring.html doc
> -----------------------------------------------
>
>                 Key: LUCENE-664
>                 URL: http://issues.apache.org/jira/browse/LUCENE-664
>             Project: Lucene - Java
>          Issue Type: Improvement
>          Components: Website
>    Affects Versions: 2.0.1
>            Reporter: Michael McCandless
>         Attachments: lucene.uxf, scoring-small-fixes.patch
>
>
> This is an awesome initiative.  We need more docs that cleanly explain the inner workings of Lucene in general... thanks Grant & Steve & others!
> I have a few small initial proposed fixes, largely just adding some more description around the components of the formula.  But also a couple typos, another link out to Wikipedia, a missing closing ), etc.  I've only made it through the "Understanding the Scoring Formula" section so far.

--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira

       

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

[jira] Commented: (LUCENE-664) [PATCH] small fixes to the new scoring.html doc

Sebastian Nagel (Jira)
In reply to this post by Sebastian Nagel (Jira)
    [ http://issues.apache.org/jira/browse/LUCENE-664?page=comments#action_12430293 ]
           
Michael McCandless commented on LUCENE-664:
-------------------------------------------

OK I did some more small fixes to the sections "Query Classes" and "Changing Similarity".  Just added some missing links, fixed a broken link, tightened up wording, etc.  I'll attach a patch.

Also a couple random questions:

  * Should this go into the Wiki or into the Web site?  Is there a general criteria / guideline that we've converged on for Wiki vs Web site?

  * Is there a reason why we are linking to the "ViewVC" page in the Big Picture section?  Can't we just link to the javadoc?

  * Should we change the title / purpose to be an overview of the Query classes and also details of scoring?  I think the Query Classes section is a great intro to the different Query classes.

> [PATCH] small fixes to the new scoring.html doc
> -----------------------------------------------
>
>                 Key: LUCENE-664
>                 URL: http://issues.apache.org/jira/browse/LUCENE-664
>             Project: Lucene - Java
>          Issue Type: Improvement
>          Components: Website
>    Affects Versions: 2.0.1
>            Reporter: Michael McCandless
>         Attachments: lucene.uxf, scoring-small-fixes.patch, scoring-small-fixes2.patch
>
>
> This is an awesome initiative.  We need more docs that cleanly explain the inner workings of Lucene in general... thanks Grant & Steve & others!
> I have a few small initial proposed fixes, largely just adding some more description around the components of the formula.  But also a couple typos, another link out to Wikipedia, a missing closing ), etc.  I've only made it through the "Understanding the Scoring Formula" section so far.

--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira

       

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

[jira] Updated: (LUCENE-664) [PATCH] small fixes to the new scoring.html doc

Sebastian Nagel (Jira)
In reply to this post by Sebastian Nagel (Jira)
     [ http://issues.apache.org/jira/browse/LUCENE-664?page=all ]

Michael McCandless updated LUCENE-664:
--------------------------------------

    Attachment: scoring-small-fixes2.patch

> [PATCH] small fixes to the new scoring.html doc
> -----------------------------------------------
>
>                 Key: LUCENE-664
>                 URL: http://issues.apache.org/jira/browse/LUCENE-664
>             Project: Lucene - Java
>          Issue Type: Improvement
>          Components: Website
>    Affects Versions: 2.0.1
>            Reporter: Michael McCandless
>         Attachments: lucene.uxf, scoring-small-fixes.patch, scoring-small-fixes2.patch
>
>
> This is an awesome initiative.  We need more docs that cleanly explain the inner workings of Lucene in general... thanks Grant & Steve & others!
> I have a few small initial proposed fixes, largely just adding some more description around the components of the formula.  But also a couple typos, another link out to Wikipedia, a missing closing ), etc.  I've only made it through the "Understanding the Scoring Formula" section so far.

--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira

       

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [jira] Commented: (LUCENE-664) [PATCH] small fixes to the new scoring.html doc

Grant Ingersoll-4
In reply to this post by Sebastian Nagel (Jira)
See below

On Aug 24, 2006, at 4:17 PM, Michael McCandless (JIRA) wrote:

>     [ http://issues.apache.org/jira/browse/LUCENE-664?
> page=comments#action_12430293 ]
>
> Michael McCandless commented on LUCENE-664:
> -------------------------------------------
>
> OK I did some more small fixes to the sections "Query Classes" and  
> "Changing Similarity".  Just added some missing links, fixed a  
> broken link, tightened up wording, etc.  I'll attach a patch.
>
> Also a couple random questions:
>
>   * Should this go into the Wiki or into the Web site?  Is there a  
> general criteria / guideline that we've converged on for Wiki vs  
> Web site?

This seems like a first level document to me.  I thought about  
putting it up on the Wiki initially so it would be easier to get  
edits done and then promote it, but in the end decided not to.  I  
think things on the Wiki get buried and ignored to some extent.  
People are always asking about scoring and the query classes and how  
to override these things, so I think that justifies it as top-level  
document in my mind.

>
>   * Is there a reason why we are linking to the "ViewVC" page in  
> the Big Picture section?  Can't we just link to the javadoc?

There are no javadocs for the ones in question, I don't think.  I  
believe the ones in question are related to BooleanWeight* and  
BooleanScorer*  The ViewVC page was a compromise of not providing any  
links.


>
>   * Should we change the title / purpose to be an overview of the  
> Query classes and also details of scoring?  I think the Query  
> Classes section is a great intro to the different Query classes.

or even split them out into a separate document????


>
>> [PATCH] small fixes to the new scoring.html doc
>> -----------------------------------------------
>>
>>                 Key: LUCENE-664
>>                 URL: http://issues.apache.org/jira/browse/LUCENE-664
>>             Project: Lucene - Java
>>          Issue Type: Improvement
>>          Components: Website
>>    Affects Versions: 2.0.1
>>            Reporter: Michael McCandless
>>         Attachments: lucene.uxf, scoring-small-fixes.patch,  
>> scoring-small-fixes2.patch
>>
>>
>> This is an awesome initiative.  We need more docs that cleanly  
>> explain the inner workings of Lucene in general... thanks Grant &  
>> Steve & others!
>> I have a few small initial proposed fixes, largely just adding  
>> some more description around the components of the formula.  But  
>> also a couple typos, another link out to Wikipedia, a missing  
>> closing ), etc.  I've only made it through the "Understanding the  
>> Scoring Formula" section so far.
>
> --
> This message is automatically generated by JIRA.
> -
> If you think it was sent incorrectly contact one of the  
> administrators: http://issues.apache.org/jira/secure/ 
> Administrators.jspa
> -
> For more information on JIRA, see: http://www.atlassian.com/ 
> software/jira
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>

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



---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [jira] Commented: (LUCENE-664) [PATCH] small fixes to the new scoring.html doc

Michael McCandless-2

>>   * Should this go into the Wiki or into the Web site?  Is there a
>> general criteria / guideline that we've converged on for Wiki vs Web
>> site?
>
> This seems like a first level document to me.  I thought about putting
> it up on the Wiki initially so it would be easier to get edits done and
> then promote it, but in the end decided not to.  I think things on the
> Wiki get buried and ignored to some extent.  People are always asking
> about scoring and the query classes and how to override these things, so
> I think that justifies it as top-level document in my mind.

OK I agree this is an important "first level" topic, and that's a good
criteria for "when Wiki" vs "when web site".

>>   * Is there a reason why we are linking to the "ViewVC" page in the
>> Big Picture section?  Can't we just link to the javadoc?
>
> There are no javadocs for the ones in question, I don't think.  I
> believe the ones in question are related to BooleanWeight* and
> BooleanScorer*  The ViewVC page was a compromise of not providing any
> links.

Aha!  You're right.  Sneaky.

>>   * Should we change the title / purpose to be an overview of the
>> Query classes and also details of scoring?  I think the Query Classes
>> section is a great intro to the different Query classes.
>
> or even split them out into a separate document????

I like the idea of splitting them and then cross referencing between.

Mike

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

RE: [jira] Commented: (LUCENE-664) [PATCH] small fixes to the new scoring.html doc

steven_parkes
In reply to this post by Sebastian Nagel (Jira)
> I think things on the
> Wiki get buried and ignored to some extent.

I've noticed there seems to be a real difference in style between the
(lucene) java subproject and the other java subprojects
nutch/hadoop/(solr). Particularly given the overlap in the dev
communities.

I wonder if the "second class" nature of the java wiki might be
addressed by "fixing it"? My initial reaction on seeing the FrontPage as
a single tabular list was a little more off putting, compared to the
style used by those other subprojects.

I think it was Doug that mentioned a while ago that a HowToContribute
page was needed. One exists for other projects' wikis but since the
style used by the other projects isn't the same, the content isn't quite
as easy to steal and place.

If there's any interest in this, I'd be up for doing some of it. I'm
climbing the learning curve anyway, so I'm up for putting in some effort
codify what I learned.

A related comment: it seems to me like the graph nature of the
abstractions/classes in Lucene makes them particularly difficult to
describe linearly. An example is the related nature of
analysis/tokenizing at index and query times. It strikes me that the
graph nature of a wiki is particularly helpful here. It helps flatten
the learning curve to be able to easily jump to a description of the
related components when reading, for example, about a particular
analyzer.

I came away feeling I wanted more in the wiki, not less.

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

RE: [jira] Commented: (LUCENE-664) [PATCH] small fixes to the new scoring.html doc

Chris Hostetter-3

: I think it was Doug that mentioned a while ago that a HowToContribute
: page was needed. One exists for other projects' wikis but since the
: style used by the other projects isn't the same, the content isn't quite
: as easy to steal and place.

Actually, there is one...

http://wiki.apache.org/jakarta-lucene/HowToContribute

...It says a lot about the state of the wiki that you couldn't find it.

I think a big part of it is that there is a lot of cruft on the wiki,
another part of it may be that the current nature of the FrontPage scares
people away from modifying it.

If you are interested in making the wiki better, I say slash and burn --
hack away anything you don't think is usefull, and if someone disagrees,
they can add it back later.



-Hoss


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [jira] Commented: (LUCENE-664) [PATCH] small fixes to the new scoring.html doc

Erik Hatcher
Another big improvement that some motivated folk(s) could tackle is  
getting the Lucene wiki moved to a more appropriate URL since we're  
no longer part of Jakarta.  I'm not sure what it'd take to move it,  
but pinging infrastructure@ would be a good place to start.

        Erik

On Aug 25, 2006, at 6:30 PM, Chris Hostetter wrote:

>
> : I think it was Doug that mentioned a while ago that a  
> HowToContribute
> : page was needed. One exists for other projects' wikis but since the
> : style used by the other projects isn't the same, the content  
> isn't quite
> : as easy to steal and place.
>
> Actually, there is one...
>
> http://wiki.apache.org/jakarta-lucene/HowToContribute
>
> ...It says a lot about the state of the wiki that you couldn't find  
> it.
>
> I think a big part of it is that there is a lot of cruft on the wiki,
> another part of it may be that the current nature of the FrontPage  
> scares
> people away from modifying it.
>
> If you are interested in making the wiki better, I say slash and  
> burn --
> hack away anything you don't think is usefull, and if someone  
> disagrees,
> they can add it back later.
>
>
>
> -Hoss
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [jira] Commented: (LUCENE-664) [PATCH] small fixes to the new scoring.html doc

Yonik Seeley-2
On 8/25/06, Erik Hatcher <[hidden email]> wrote:
> Another big improvement that some motivated folk(s) could tackle is
> getting the Lucene wiki moved to a more appropriate URL since we're
> no longer part of Jakarta.

There also appears to be new wiki software in town:
http://cwiki.apache.org/

-Yonik

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

[jira] Commented: (LUCENE-664) [PATCH] small fixes to the new scoring.html doc

Sebastian Nagel (Jira)
In reply to this post by Sebastian Nagel (Jira)
    [ http://issues.apache.org/jira/browse/LUCENE-664?page=comments#action_12430812 ]
           
Grant Ingersoll commented on LUCENE-664:
----------------------------------------

Hi Michael,

Correct me if I am wrong, but does the second patch include the first patch, too?  I have already committed the first, so if you could update and add a new version of the patch with your latest edits, that would be great.

Thanks,
Grant

> [PATCH] small fixes to the new scoring.html doc
> -----------------------------------------------
>
>                 Key: LUCENE-664
>                 URL: http://issues.apache.org/jira/browse/LUCENE-664
>             Project: Lucene - Java
>          Issue Type: Improvement
>          Components: Website
>    Affects Versions: 2.0.1
>            Reporter: Michael McCandless
>         Attachments: lucene.uxf, scoring-small-fixes.patch, scoring-small-fixes2.patch
>
>
> This is an awesome initiative.  We need more docs that cleanly explain the inner workings of Lucene in general... thanks Grant & Steve & others!
> I have a few small initial proposed fixes, largely just adding some more description around the components of the formula.  But also a couple typos, another link out to Wikipedia, a missing closing ), etc.  I've only made it through the "Understanding the Scoring Formula" section so far.

--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira

       

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

[jira] Updated: (LUCENE-664) [PATCH] small fixes to the new scoring.html doc

Sebastian Nagel (Jira)
In reply to this post by Sebastian Nagel (Jira)
     [ http://issues.apache.org/jira/browse/LUCENE-664?page=all ]

Michael McCandless updated LUCENE-664:
--------------------------------------

    Attachment: scoring-small-fixes3.patch

Doh!  You are correct.  OK I re-based the diffs off the current version.  Sorry about that.

> [PATCH] small fixes to the new scoring.html doc
> -----------------------------------------------
>
>                 Key: LUCENE-664
>                 URL: http://issues.apache.org/jira/browse/LUCENE-664
>             Project: Lucene - Java
>          Issue Type: Improvement
>          Components: Website
>    Affects Versions: 2.0.1
>            Reporter: Michael McCandless
>         Attachments: lucene.uxf, scoring-small-fixes.patch, scoring-small-fixes2.patch, scoring-small-fixes3.patch
>
>
> This is an awesome initiative.  We need more docs that cleanly explain the inner workings of Lucene in general... thanks Grant & Steve & others!
> I have a few small initial proposed fixes, largely just adding some more description around the components of the formula.  But also a couple typos, another link out to Wikipedia, a missing closing ), etc.  I've only made it through the "Understanding the Scoring Formula" section so far.

--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira

       

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

[jira] Commented: (LUCENE-664) [PATCH] small fixes to the new scoring.html doc

Sebastian Nagel (Jira)
In reply to this post by Sebastian Nagel (Jira)
    [ http://issues.apache.org/jira/browse/LUCENE-664?page=comments#action_12431302 ]
           
Grant Ingersoll commented on LUCENE-664:
----------------------------------------

Committed patch 3.  Thanks Michael!

> [PATCH] small fixes to the new scoring.html doc
> -----------------------------------------------
>
>                 Key: LUCENE-664
>                 URL: http://issues.apache.org/jira/browse/LUCENE-664
>             Project: Lucene - Java
>          Issue Type: Improvement
>          Components: Website
>    Affects Versions: 2.0.1
>            Reporter: Michael McCandless
>         Attachments: lucene.uxf, scoring-small-fixes.patch, scoring-small-fixes2.patch, scoring-small-fixes3.patch
>
>
> This is an awesome initiative.  We need more docs that cleanly explain the inner workings of Lucene in general... thanks Grant & Steve & others!
> I have a few small initial proposed fixes, largely just adding some more description around the components of the formula.  But also a couple typos, another link out to Wikipedia, a missing closing ), etc.  I've only made it through the "Understanding the Scoring Formula" section so far.

--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira

       

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

[jira] Commented: (LUCENE-664) [PATCH] small fixes to the new scoring.html doc

Sebastian Nagel (Jira)
In reply to this post by Sebastian Nagel (Jira)
    [ http://issues.apache.org/jira/browse/LUCENE-664?page=comments#action_12431631 ]
           
Doug Cutting commented on LUCENE-664:
-------------------------------------

This is good stuff.  Might it be better to include this in the javadoc? That way, as the code evolves, the documentation is more naturally maintained, since search-and-replace operations etc. will find it.  I worry that as soon as this documentation is complete, we'll change the implementation and invalidate it.

> [PATCH] small fixes to the new scoring.html doc
> -----------------------------------------------
>
>                 Key: LUCENE-664
>                 URL: http://issues.apache.org/jira/browse/LUCENE-664
>             Project: Lucene - Java
>          Issue Type: Improvement
>          Components: Website
>    Affects Versions: 2.0.1
>            Reporter: Michael McCandless
>         Attachments: lucene.uxf, scoring-small-fixes.patch, scoring-small-fixes2.patch, scoring-small-fixes3.patch
>
>
> This is an awesome initiative.  We need more docs that cleanly explain the inner workings of Lucene in general... thanks Grant & Steve & others!
> I have a few small initial proposed fixes, largely just adding some more description around the components of the formula.  But also a couple typos, another link out to Wikipedia, a missing closing ), etc.  I've only made it through the "Understanding the Scoring Formula" section so far.

--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira

       

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

[jira] Commented: (LUCENE-664) [PATCH] small fixes to the new scoring.html doc

Sebastian Nagel (Jira)
In reply to this post by Sebastian Nagel (Jira)
    [ http://issues.apache.org/jira/browse/LUCENE-664?page=comments#action_12431645 ]
           
Grant Ingersoll commented on LUCENE-664:
----------------------------------------

Yeah, I thought about putting it in Javadoc and I share your concern about invalidation, but I think that is always the case with all documentation, including javadocs, and is just something we have to live with and work on.  I also think it is bigger picture than javadocs and spans multiple packages, so it doesn't really fit as nicely into the Javadoc model of package level documentation.   My hope is that by making it a part of the main site and something people can easily find it will be better maintained.

> [PATCH] small fixes to the new scoring.html doc
> -----------------------------------------------
>
>                 Key: LUCENE-664
>                 URL: http://issues.apache.org/jira/browse/LUCENE-664
>             Project: Lucene - Java
>          Issue Type: Improvement
>          Components: Website
>    Affects Versions: 2.0.1
>            Reporter: Michael McCandless
>         Attachments: lucene.uxf, scoring-small-fixes.patch, scoring-small-fixes2.patch, scoring-small-fixes3.patch
>
>
> This is an awesome initiative.  We need more docs that cleanly explain the inner workings of Lucene in general... thanks Grant & Steve & others!
> I have a few small initial proposed fixes, largely just adding some more description around the components of the formula.  But also a couple typos, another link out to Wikipedia, a missing closing ), etc.  I've only made it through the "Understanding the Scoring Formula" section so far.

--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira

       

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

[jira] Commented: (LUCENE-664) [PATCH] small fixes to the new scoring.html doc

Sebastian Nagel (Jira)
In reply to this post by Sebastian Nagel (Jira)
    [ http://issues.apache.org/jira/browse/LUCENE-664?page=comments#action_12431669 ]
           
Steven Parkes commented on LUCENE-664:
--------------------------------------

I went through basically the same reasoning that Grant describes, particularly with loading the javadocs w/too much stuff. But I do like the wiki ability to give you linking akin to that in javadocs.

As to renaming the wiki url (mentioned on dev though not in jira), I'm happy to approach infrastructure. My concern would be external links into the wiki that reference the old jakarata url. I guess we could find out if they can handle a redirect from jakarata-lucene/* to lucene/*?

> [PATCH] small fixes to the new scoring.html doc
> -----------------------------------------------
>
>                 Key: LUCENE-664
>                 URL: http://issues.apache.org/jira/browse/LUCENE-664
>             Project: Lucene - Java
>          Issue Type: Improvement
>          Components: Website
>    Affects Versions: 2.0.1
>            Reporter: Michael McCandless
>         Attachments: lucene.uxf, scoring-small-fixes.patch, scoring-small-fixes2.patch, scoring-small-fixes3.patch
>
>
> This is an awesome initiative.  We need more docs that cleanly explain the inner workings of Lucene in general... thanks Grant & Steve & others!
> I have a few small initial proposed fixes, largely just adding some more description around the components of the formula.  But also a couple typos, another link out to Wikipedia, a missing closing ), etc.  I've only made it through the "Understanding the Scoring Formula" section so far.

--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira

       

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

[jira] Commented: (LUCENE-664) [PATCH] small fixes to the new scoring.html doc

Sebastian Nagel (Jira)
In reply to this post by Sebastian Nagel (Jira)
    [ http://issues.apache.org/jira/browse/LUCENE-664?page=comments#action_12431954 ]
           
Doug Cutting commented on LUCENE-664:
-------------------------------------

Javadoc is easiest to keep in sync with changes to the code, since it is in the same files.  The wiki is the hardest to keep in sync with the code, since it is not versioned with the code.  We website is somewhere between: it is in subversion, but in separate files in a separate tree.

The javadoc is thus the preferred location for documentation that is specific to the code.  The website and wiki are better for stuff that's specific to the project: policys, procedures, etc.  The wiki is great for user-generated stuff like benchmarks, porting tricks, use cases, etc.

This stuff seems pretty closely tied to the code, so I'd put it in the javadoc.  It's nearly all stuff that's in the search package, so much of this could go in search/package.html with pointers to the javadoc for Query, Weight, Scorer, etc.

> [PATCH] small fixes to the new scoring.html doc
> -----------------------------------------------
>
>                 Key: LUCENE-664
>                 URL: http://issues.apache.org/jira/browse/LUCENE-664
>             Project: Lucene - Java
>          Issue Type: Improvement
>          Components: Website
>    Affects Versions: 2.0.1
>            Reporter: Michael McCandless
>         Attachments: lucene.uxf, scoring-small-fixes.patch, scoring-small-fixes2.patch, scoring-small-fixes3.patch
>
>
> This is an awesome initiative.  We need more docs that cleanly explain the inner workings of Lucene in general... thanks Grant & Steve & others!
> I have a few small initial proposed fixes, largely just adding some more description around the components of the formula.  But also a couple typos, another link out to Wikipedia, a missing closing ), etc.  I've only made it through the "Understanding the Scoring Formula" section so far.

--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira

       

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

RE: [jira] Commented: (LUCENE-664) [PATCH] small fixes to the new scoring.html doc

steven_parkes
For my part, I was thinking more about material along the lines of 1.5
(Understanding the core indexing classes) and 1.6 (Understanding the
core searching classes) in LIA. It strikes me that javadocs are little
hard-core for that. A little difficult for the beginner to absorb. More
reference than tutorial?

Assuming then that we do have material that shouldn't go into the
javadocs, where should it go? As far as I can tell, material like that
in LIA doesn't exist right now, at least not on an apache site. Maybe I
missed it?

I thought about the versioning issue with the wiki and I failed to come
up with a solution. Versioning the wiki seems to not make sense. I can
see the reasoning behind putting tutorial material in the website, but I
would so miss WikiWords.

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [jira] Commented: (LUCENE-664) [PATCH] small fixes to the new scoring.html doc

Chris Hostetter-3
In reply to this post by Sebastian Nagel (Jira)
: Javadoc is easiest to keep in sync with changes to the code, since it is
: in the same files.  The wiki is the hardest to keep in sync with the
: code, since it is not versioned with the code.  We website is somewhere
: between: it is in subversion, but in separate files in a separate tree.

the seperation of hte site in the tree certainly makes keeping them in
sync less easy then keeping the javadocs in sync -- but the fact that the
"site" at the moment of a release is bundled in with the release makes it
a pretty optimal place for things like this.

that said, it certainly seems like sections of the scoring.html might make
more sense in the javadocs, leaving the file to be more of a "skeleton" of
links out .. likewise this doc should be refrenced by more links *from*
javadocs of various classes.

if this was something i was building for work, i'd put all of this info
in a doc-files directory so it was completely bundled with both the source
code and any build of the javadocs -- but nobody i work with really agrees
with me that doc-files directories are cool either.




-Hoss


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

123