lucene-solr-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ryan McKinley <ryan...@gmail.com>
Subject Re: Confluence wiki vs MoinMoin
Date Thu, 13 Dec 2007 14:43:22 GMT
Chris Hostetter wrote:
> : Javadocs aren't appropriate for documenting configuration and RequestHandler
> : parameters/usage.  These are used by many non-java folks and should have
> : nothing to do with the java class structure/methods/etc
> 
> i agree that the generated javadocs are not very freindly for end users, 
> but i think there is a lot of value in this kind of documentation living 
> in the code so it can be kept uptodate as the code is changed (hence my 
> suggestion about maybe having a custom doclet for generating a more user 
> freindly output of just the freeform "class" javadocs (without the methods 
> and package structure information)
> 

As long as we have a consistent answer for where param/behavior docs go, 
I'm happy with (almost) any convention.  Perhaps all 'end-user' docs 
would go under:
http://lucene.apache.org/solr/api/org/apache/solr/common/params/package-summary.html

In my view the best approach may be:
'end-user' docs (params+behavior/use cases/configuration) goes in cwiki
'plugin' overview in cwiki
'plugin' details in javadocs
Implementation details in javadocs.  Javadocs should link to the 
relevant cwiki page for usage.


> 
> : My thought is that nothing new would go there.  Hopefully we could make the
> : "sandbox" a section of cwiki with no user permissions that does not get
> : included in the docs.
> 
> that's great ... but it stil leaves the MoinMoin wiki getting old, 
> stagnent, looking different from everything else, and requiring a 
> differnet syntax to be edited (like when we want to note that a param has 
> been deprecated in later versions of Solr or something) ... it becomes an 
> "image problem" to leave it up and running for very long.
> 

In my plan, the MoinMoin wiki would be accurate for release 1.2 -- it 
should stay around as long as 1.2 is a useful release.  This would not 
get updated docs even if they are 1.2 relevant.  (unless someone REALLY 
wants to update them)

As long as the pages are well marked with a warning that new stuff is on 
a different site and contains a link to that site I think the image is ok.

ryan




Mime
View raw message