FAQ
One of the things that seems to work really well in Solr for
documentation is that people seem to be of the mindset that any time
some new feature is developed or a significant change is being made, a
Wiki page is added/updated. I think this would be a really good habit
for us in Lucene to get in the habit of doing. For instance, Jason
opened https://issues.apache.org/jira/browse/SOLR-1277 (ZooKeeper
integration for Solr) and I put up a patch and also started a Wiki
page on it: http://wiki.apache.org/solr/ZooKeeperIntegration. We also
tend to do this in Mahout, too. Now, going forward, those wanting to
understand how to use and install the patch can go to the wiki page
instead of just trying to figure out the patch.

It has a few benefits I can think of:

1. Lengthy discussions in JIRA, while important, often become
confusing to come into later and to figure out what exactly is the
state of the patch and how it works
2. We have real documentation on new features and existing features
get updated
3. It forces the patch writer to explain the code, which often leads
to better code
4. It lets others be involved in the documentation process.

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

Search Discussions

  • Michael Busch at Jul 21, 2009 at 11:15 pm
    Couldn't we just update the description of the Jira issue itself so that
    it reflects the current state of the patch? Often the inital description
    of a Jira issue is never updated after the issue is created, even though
    the patch and goals changed as discussions happened. I think that would
    be more convenient than having in addition a wiki page?

    Michael
    On 7/21/09 5:57 AM, Grant Ingersoll wrote:
    One of the things that seems to work really well in Solr for
    documentation is that people seem to be of the mindset that any time
    some new feature is developed or a significant change is being made, a
    Wiki page is added/updated. I think this would be a really good habit
    for us in Lucene to get in the habit of doing. For instance, Jason
    opened https://issues.apache.org/jira/browse/SOLR-1277 (ZooKeeper
    integration for Solr) and I put up a patch and also started a Wiki
    page on it: http://wiki.apache.org/solr/ZooKeeperIntegration. We also
    tend to do this in Mahout, too. Now, going forward, those wanting to
    understand how to use and install the patch can go to the wiki page
    instead of just trying to figure out the patch.

    It has a few benefits I can think of:

    1. Lengthy discussions in JIRA, while important, often become
    confusing to come into later and to figure out what exactly is the
    state of the patch and how it works
    2. We have real documentation on new features and existing features
    get updated
    3. It forces the patch writer to explain the code, which often leads
    to better code
    4. It lets others be involved in the documentation process.

    ---------------------------------------------------------------------
    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
  • Michael Busch at Jul 21, 2009 at 11:18 pm
    Hmm... of course for big things like e.g. "Flexible Indexing" a wiki
    page is useful, in case the feature is developed in multiple Jira
    issues. But e.g. for the TokenStream patch we could just update the
    description of 1693.

    Michael
    On 7/21/09 4:17 PM, Michael Busch wrote:
    Couldn't we just update the description of the Jira issue itself so
    that it reflects the current state of the patch? Often the inital
    description of a Jira issue is never updated after the issue is
    created, even though the patch and goals changed as discussions
    happened. I think that would be more convenient than having in
    addition a wiki page?

    Michael
    On 7/21/09 5:57 AM, Grant Ingersoll wrote:
    One of the things that seems to work really well in Solr for
    documentation is that people seem to be of the mindset that any time
    some new feature is developed or a significant change is being made,
    a Wiki page is added/updated. I think this would be a really good
    habit for us in Lucene to get in the habit of doing. For instance,
    Jason opened https://issues.apache.org/jira/browse/SOLR-1277
    (ZooKeeper integration for Solr) and I put up a patch and also
    started a Wiki page on it:
    http://wiki.apache.org/solr/ZooKeeperIntegration. We also tend to do
    this in Mahout, too. Now, going forward, those wanting to understand
    how to use and install the patch can go to the wiki page instead of
    just trying to figure out the patch.

    It has a few benefits I can think of:

    1. Lengthy discussions in JIRA, while important, often become
    confusing to come into later and to figure out what exactly is the
    state of the patch and how it works
    2. We have real documentation on new features and existing features
    get updated
    3. It forces the patch writer to explain the code, which often leads
    to better code
    4. It lets others be involved in the documentation process.

    ---------------------------------------------------------------------
    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
  • Chris Hostetter at Jul 21, 2009 at 11:22 pm
    : Couldn't we just update the description of the Jira issue itself so that it
    : reflects the current state of the patch? Often the inital description of a
    : Jira issue is never updated after the issue is created, even though the patch
    : and goals changed as discussions happened. I think that would be more
    : convenient than having in addition a wiki page?

    That covers #1 of grants points, but not #2-4

    for those not familiar with the process happening in solr, there isn't a
    seperate wiki page for every jira issue -- there is a seperate jira page
    for each major component/feature. people submitting patches which add new
    functionality either write a new wiki page (if it's a radically new
    feature) or update an existing wiki page to include a new section which
    has a note inidcating the the documentation refers to uncommited changes
    pending a jira issue (and link to it). When patches are finally
    committed, people remove the caveat warning form the wiki -- but even if
    they forget, someone else can notice later that the linked issue is
    resolved and remove it then.

    the end result is documentation on features that lives long after the
    issue creating the feature goes away.

    : > 1. Lengthy discussions in JIRA, while important, often become confusing to
    : > come into later and to figure out what exactly is the state of the patch and
    : > how it works
    : > 2. We have real documentation on new features and existing features get
    : > updated
    : > 3. It forces the patch writer to explain the code, which often leads to
    : > better code
    : > 4. It lets others be involved in the documentation process.




    -Hoss


    ---------------------------------------------------------------------
    To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
    For additional commands, e-mail: java-dev-help@lucene.apache.org
  • Michael Busch at Jul 21, 2009 at 11:32 pm

    On 7/21/09 4:23 PM, Chris Hostetter wrote:
    for those not familiar with the process happening in solr, there isn't a
    seperate wiki page for every jira issue -- there is a seperate jira page
    for each major component/feature. people submitting patches which add new
    OK, I agree this makes sense and would be good for major features.

    Btw: For the new TokenStream API I wrote in the original patch
    (JIRA-1422) a quite elaborate section in the package.html of the
    analysis package.

    Michael

    ---------------------------------------------------------------------
    To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
    For additional commands, e-mail: java-dev-help@lucene.apache.org
  • Chris Hostetter at Jul 21, 2009 at 11:45 pm
    : OK, I agree this makes sense and would be good for major features.
    :
    : Btw: For the new TokenStream API I wrote in the original patch (JIRA-1422) a
    : quite elaborate section in the package.html of the analysis package.

    Yeah ... whenever javadocs make sense, they're probably better then wiki
    docs ... in the case of Solr the userbase is rarely Java users, so it's
    good to have hollistic documentation somewhere other then javadocs.

    To me, the key is to make sure all functionality is documented *somewhere*
    before it gets committed. if it makes sense in javadocs great, if it's
    too widespread to fit neatly into the javadoc method/class/package
    structure, a wiki ting everything together is handy.

    That said: even with simple javadocs, having them on the wiki makes it a
    lot easier to read then needing to downlaod/apply the patch *then*
    generate javadocs to read the cross linked info.


    -Hoss


    ---------------------------------------------------------------------
    To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
    For additional commands, e-mail: java-dev-help@lucene.apache.org
  • Michael McCandless at Jul 22, 2009 at 12:10 am

    On Tue, Jul 21, 2009 at 7:45 PM, Chris Hostetterwrote:

    To me, the key is to make sure all functionality is documented *somewhere*
    before it gets committed.  if it makes sense in javadocs great, if it's
    too widespread to fit neatly into the javadoc method/class/package
    structure, a wiki ting everything together is handy.
    +1

    I think for many of Lucene's features, good javadocs is what we
    need... and then for big features, good javadocs plus a wiki page
    makes sense.

    Mike

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

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
groupjava-dev @
categorieslucene
postedJul 21, '09 at 12:56p
activeJul 22, '09 at 12:10a
posts7
users4
websitelucene.apache.org

People

Translate

site design / logo © 2021 Grokbase