lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Jack Krupansky" <j...@basetechnology.com>
Subject Test cases for Solr wiki/ref guide consolidation policy
Date Sat, 03 Aug 2013 21:11:59 GMT
[Is there an active Jira issue where these comments belong?]

Here are two great test case for the issue of how to switch over from the old Solr wiki to
the new Confluence-based Solr Reference Guide: the terms component and the term vector component.

1. The ref guide is virtually identical to the wiki anyway for these two pages. No apparent
need to move any info over or worry about loss of info. IOW, 100% overlap
2. If anybody does want to update either of these two pages, it would be nice to be clear
what the status of the wiki page is. Maybe it should have a banner indicating that it is historic/archive.
3. Should the wiki be kept as is and simply add a “pointer” to the ref guide?
4. Or should the wiki be “stubbed out” and point to the ref guide only?
5. Or should the wiki page be deleted and any referencing pages in the wiki re-point to the
ref guide. There may be non-Solr web pages that link to the wiki page. A 301 redirect would
be nice.

There are three other interesting issues with these two test cases:

1. They both have Javadoc which, as they say, “needs some love” – should the Javadoc
be updated, maintained, encouraged, etc?
2. Should a pointer to the ref guide be added to the Javadoc? There are plenty of cases in
Solr where the Javadoc is spotty, missing or explicitly “TO DO”; a policy for dealing
with it  is needed – may simply linking to the closest ref guide page is the next step.
3. Both have additional DEFINITIVE reference documentation... in the Solr example solrconfig.xml.
How much info should go into the Javadoc vs. solrconfig vs. ref guide? Some day we will finally
have multiple example config/schemas; then solrconfig might not be the best place to use as
the master for doc info.

I did notice that the Javadoc for the term vector component has a copy-paste bug – it names
the request handler “/terms”, while in solrconfig it is properly named “/tvrh”. The
new ref guide has the same “bug”.

-- Jack Krupansky
Mime
View raw message