even if we switch to cwiki, I still think javadocs are the best way to go
for "official" plugin docs because of hte code/doc proximity advantages
... but if they aren't user friendly enough for typical users then maybe
we could look into hacking together a custom doclet to just output the
class level docs and not hte method details?
For plugin/embedded docs, I agree javadocs are the correct place.
Plugin authors need to be java savvy and will be working with the java
interfaces, so there is no need for special doclet.
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
: Having read all the rules, this is my proposal:
+1 to the bulk of your proposal, but a few comments...
I would like to suggest a step #0: There doesn't seem to be a cwiki
sandbox we can use to test stuff out, so after getting a solr cwiki
created, let's do some experiments with the exporting and make sure we can
viably export docs that:
1) use all relative links (like forrest)
2) don't contain "user comments" from non cla users
..so we can be confident the exports can be included as documentation with
releases before we spend a lot of time building up the new docset.
I'm not sure #2 is a big deal. The cwiki info site specifically says
"Incidental comments about a page would not require that a CLA to be on
file" Assuming we all get notified of all changes, inappropriate
comments would be deleted and substantial ones likely integrated into
the main page. "Incidental" ones could remain as is.
But yes, I agree we should set it up and play with it before committing
to it.
: 2. We keep http://wiki.apache.org/solr/ as an unofficial sandbox and pre 1.3
: docs. Anyone can edit it, but it is not official.
i'm assuming we might eventually want to migrate this to a seperate
cwiki space just for our own sanity (single syntax, single look/feel,
etc...) but i agree this doesn't need to happen any time soon.
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.
: For now, i think we should stick with forrest for the website and tutorial.
: When the tutorial gets revisited, http://cwiki.apache.org/SOLRxSITE/ may be a
i think the current site (including the tutorial) would probably make the
best "initial" docs to put into the new cwiki to test it out since we
*know* the legal issues with them are okay and we know they should be
included in all releases. eliminating forrest from the equation
early on would also help simplify the "documentation dilution" issues of
having forrest docs, wiki docs, and cwiki docs all at once -- especially
if in Solr 1.3 (or 1.4 ... whenever it happens) the release itself
includes overview docs and a tutorial generated by forrest with other docs
generated from a cwiki dump ... the odds of getting those to all hyperlink
with eachother cleanly seems very low.
yup.
Do we feel ok about moving forward with step #0? That is request a
cwiki site and evaluate it.
ryan
