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: [email protected]
For additional commands, e-mail: [email protected]
