SOLR-555 ... Solr 1.3?

[Chris Hostetter <ho...@fucit.org>]

I'd hoped to be long done with SOLR-555 by now, have it all polished and 
spiffy and committed ... but it's not.

The meat is there, it functions and does everything i want it to do, the 
only reasons I've been hesitent to commit are:
   1) Some of the internals are a bit kludgy
   2) It doesn't do a lot of error checking / warning about the new custom
      javadoc tags being used improperly.
   3) The html pages currently created aren't very pretty
   4) Is there anypoint in rushing it?  Will we realy try to fill in some
      good user docs prior to 1.3 if we commit this now?

#1 probably isn't that big of deal since it's only a build tool.  End 
users never run it, we don't really need to worry about users extending 
it, etc... i can make it better later if/when i have time, but unless 
somebody else thinks it's really a bad idea, this isn't a show stopper.

#2 would be nice to take care of since nobdy is perfect and getting 
warnings about documentation glitches is a nice way to spot them ... but 
we shouldn't refrain from using a tool that makes writing documentation we 
don't have easier just because it won't neccessarily warn us when there is 
a mistake in our docs. (again: unless anyone has a strong opinoin, not a 
show stopper)

#3 and #4 are really the only big questionable things ... is it worth it 
to start using this, and start generating better documentation that we can 
include in 1.3 even if the documentation isn't pretty to look at?  Will we 
take the time before releasing to fill in the documentation so it's 
actually useful?  ... or should we hold off, stick with the status quo 
(all "user" docs are in wiki pages)  and worry about after 1.3?


 				?

-Hoss

Re: SOLR-555 ... Solr 1.3?

[Chris Hostetter <ho...@fucit.org>]

: For QParser specifically, It's slightly awkward to have the class
: names as the titles, esp when the majority of users may be looking for
: the syntax to put in "q", not for any Java class related stuff.

not really sure how to make that better ... the classnames should be 
descriptive about what the plugin does, and the classname is what you need 
to know to register the plugin in your configs.

I still expect that in addition to "programatic" docs like this, we need 
to beef up our "guides" for people, talking about the default usages 
and common cases -- places where we can say "this kind of use cases is 
where defType=dismax makes sense ... and then link over to these 
autogenerated docs for the details about what exactly this 
DismaxQParserPlugin does (and at the top of hte page, where you see the 
general docs about QParserPlugin, we would have an example of how to 
register custom QParserPlugin's with special names and init params and so 
on.

: It's also a fact of life that we will need to change/add docs after a
: release.  How would this be done?  Doc commits and doc regeneration
: (with the website linking to trunk?)   That works for small changes,
: but what about big ones (class renames, removes, etc).  That suggests
: that the doc changes should also be merged onto the release-specific
: branch.... more work.

I'm not sure what you mean ... the docs on the trunk apply to the trunk, 
the docs that ship with a release apply to that release -- no different 
from javadocs or the tutorial today.  one of the big motivations for me 
about trying to generate good "user" docs is that they can ship with the 
releases so you know exactly what plugins you've got in your version and 
what options they support, and we don't have to rely on special wiki 
markup to keep straight that a certain param wasn't added untill Solr 3.9

The wiki will certain still have it's place for "tips and tricks" and 
"user comments" put the primarily docs will ship with the release (and in 
the interest of SEO and convinient access, we can put them online in 
"past releases" directories just like other apache projects)

: I'm fine with it going in now though... we don't actually have to
: point to the generated docs if we don't want to for this release, or
: we could pick and choose parts to point to from the Wiki, right?

yeah ... i'll try to do this in the next few days, i need to make sure i 
do it in a way that plays nice with the SolrJ and contrib javadoc changes 
Shalin is/was doing/did (something i hadn't thought about until recently)



-Hoss

Re: SOLR-555 ... Solr 1.3?

[Yonik Seeley <yo...@apache.org>]

Interesting stuff... and immediately applicable since I need to doc
the QParser stuff.
http://people.apache.org/~hossman/tmp/SOLR-555/plugins/org.apache.solr.search.QParserPlugin.html

For QParser specifically, It's slightly awkward to have the class
names as the titles, esp when the majority of users may be looking for
the syntax to put in "q", not for any Java class related stuff.

It's also a fact of life that we will need to change/add docs after a
release.  How would this be done?  Doc commits and doc regeneration
(with the website linking to trunk?)   That works for small changes,
but what about big ones (class renames, removes, etc).  That suggests
that the doc changes should also be merged onto the release-specific
branch.... more work.

I'm fine with it going in now though... we don't actually have to
point to the generated docs if we don't want to for this release, or
we could pick and choose parts to point to from the Wiki, right?

-Yonik

On Thu, Jul 31, 2008 at 7:11 PM, Chris Hostetter
<ho...@fucit.org> wrote:
>
> I'd hoped to be long done with SOLR-555 by now, have it all polished and
> spiffy and committed ... but it's not.
>
> The meat is there, it functions and does everything i want it to do, the
> only reasons I've been hesitent to commit are:
>  1) Some of the internals are a bit kludgy
>  2) It doesn't do a lot of error checking / warning about the new custom
>     javadoc tags being used improperly.
>  3) The html pages currently created aren't very pretty
>  4) Is there anypoint in rushing it?  Will we realy try to fill in some
>     good user docs prior to 1.3 if we commit this now?
>
> #1 probably isn't that big of deal since it's only a build tool.  End users
> never run it, we don't really need to worry about users extending it, etc...
> i can make it better later if/when i have time, but unless somebody else
> thinks it's really a bad idea, this isn't a show stopper.
>
> #2 would be nice to take care of since nobdy is perfect and getting warnings
> about documentation glitches is a nice way to spot them ... but we shouldn't
> refrain from using a tool that makes writing documentation we don't have
> easier just because it won't neccessarily warn us when there is a mistake in
> our docs. (again: unless anyone has a strong opinoin, not a show stopper)
>
> #3 and #4 are really the only big questionable things ... is it worth it to
> start using this, and start generating better documentation that we can
> include in 1.3 even if the documentation isn't pretty to look at?  Will we
> take the time before releasing to fill in the documentation so it's actually
> useful?  ... or should we hold off, stick with the status quo (all "user"
> docs are in wiki pages)  and worry about after 1.3?
>
>
>                                ?
>
> -Hoss
>
>

Re: SOLR-555 ... Solr 1.3?

[Andrew Savory <as...@apache.org>]

Hey there,

2008/8/1 Chris Hostetter <ho...@fucit.org>:

> I'd hoped to be long done with SOLR-555 by now, have it all polished and
> spiffy and committed ... but it's not.

Autogenerate "user" docs about "plugins" from code,
http://issues.apache.org/jira/browse/SOLR-555

> is it worth it to
> start using this, and start generating better documentation that we can
> include in 1.3 even if the documentation isn't pretty to look at?  Will we
> take the time before releasing to fill in the documentation so it's actually
> useful?  ... or should we hold off, stick with the status quo (all "user"
> docs are in wiki pages)  and worry about after 1.3?

I'd suggest "commit early, commit often", especially for something
that is not API-level and therefore problematic if it's changed. This
gives other people the opportunity to work on the three things you
list that need improvement, and also allows anyone to start writing
docs. If lots of docs are added before 1.3, great. If they aren't, no
problem.


Andrew.
--
asavory@apache.org / contact@andrewsavory.com
http://www.andrewsavory.com/