FAQ
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

Search Discussions

  • Yonik Seeley at Aug 1, 2008 at 4:13 am
    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
    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
  • Chris Hostetter at Aug 5, 2008 at 3:30 am
    : 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
  • Andrew Savory at Aug 1, 2008 at 8:32 am
    Hey there,

    2008/8/1 Chris Hostetter <hossman_lucene@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/

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
groupsolr-dev @
categorieslucene
postedJul 31, '08 at 11:12p
activeAug 5, '08 at 3:30a
posts4
users3
websitelucene.apache.org...

People

Translate

site design / logo © 2019 Grokbase