You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lucene.apache.org by Grant Ingersoll <gs...@apache.org> on 2009/07/21 14:57:06 UTC
Documentation Suggestion
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
Re: Documentation Suggestion
Posted by Michael Busch <bu...@gmail.com>.
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
Re: Documentation Suggestion
Posted by Michael McCandless <lu...@mikemccandless.com>.
On Tue, Jul 21, 2009 at 7:45 PM, Chris
Hostetter<ho...@fucit.org> wrote:
> 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
Re: Documentation Suggestion
Posted by Chris Hostetter <ho...@fucit.org>.
: 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
Re: Documentation Suggestion
Posted by Michael Busch <bu...@gmail.com>.
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
Re: Documentation Suggestion
Posted by Chris Hostetter <ho...@fucit.org>.
: 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
Re: Documentation Suggestion
Posted by Michael Busch <bu...@gmail.com>.
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