lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Chris Hostetter <hossman_luc...@fucit.org>
Subject Re: Changing our Wiki software?
Date Thu, 09 Feb 2012 20:24:17 GMT

FWIW: i have almost no opinion at all on what wiki software we use, but 
that really just seems like the seed of this conversation...

: Specific to Solr, I think we should drop all the "back compat" in our
: documentation and target it toward 4.0

In an ideal world, i think the best way to organize all of this stuff 
would be...

-- BEGIN: IDEAL WORLD --

1) "official documentation" (even solr user level, non-javadoc type 
information) would be live in the source tree and branched/packaged with 
each release, so every user has a copy of the docs that affect them.

2) "official documentation" for the last N versions would be snapshoted on 
the website

3) the wiki would be solely for "unofficial documentation" (ie: faq, tips 
and tricks, recepies).  it would be world editable, and we could be very 
ruthless about pruning away info that only applies to old releases so that 
the only "version specific caveats" we'd have to deal with would be any 
subtleties between bug fix versions (ie: 3.6.2, vs 4.2 vs trunk as a 
hypothetical example) -- users of older versions would have the complete 
"official documentation" and they could always look through the wiki page 
history arround the date of their versions release to see what 
tips/ticks/caveats might have been listed back then.

4) The "official documentation" should liberaly and judiciously link out 
to the "unofficial documentation" with boilerplate links like "More info 
about this [feature|class|module|plugin|etc...] may be found <a 
href='${wikiurl}'>on the wiki</a>" ... even if $wikiurl doesn't exist at 
the time of writing, so that users who want to contribute tips/tricks 
about a particular feature/class/module/plugin/etc.. have a ready made 
place to do so.

-- END: IDEAL WORLD --

Now, having said that, i have no idea how to sanely migrate from the world 
we live in today to that ideal world (even if everyone agreed it would be 
ideal).  

For solr user documentation about plugins, i sort of started down this 
road once upon a time with SOLR-555, but it fell by the way side since 
there didn't seem to be much interest from other people in helping to 
polish it up and start taking advantage of it (particularly since there 
would be a lot of initial work to migrate the param info into the new 
javadoclet tags that i did not have the energy to deal with by myself).  
Even if we had that and all the javadocs were perfect and all the params 
were documented perfectly, it wouldn't help us with things like the solr 
tutorial or any of the other forrest generated docs for lucene-core users 
which we also need to think about.

There's also the issue of dealing with users of older versions ... if we 
magically pushed a button and had the perfect line between "official 
documentation" and "unofficial documentation" that i mentioned above for 
4.0, i'd still be leary of prunning the solr wiki of info about older 
versions because users of those older versions wouldn't have any 
"official" documentation for themselves. (time travel is hard)

Coming full circle...

If there is an ideal world, and we all agreed about what it looks like, 
and a concentrated effort is made to make that ideal world a reality, 
then perhaps switching wiki software might actually be a good way to deal 
with the problem of legacy users:

 a) create newer/better "official documentation" (somewhere)
 b) create new confluence wikis for "unofficial documentation" 
    contributed by users
 c) make the existing moinmoin wikis read only with a big caveat 
    at the top that they contain historic information for users 
    of old versions of lucene/solr and users of new versions 
    should instead link to {a} and {b}



-Hoss

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


Mime
View raw message