: What is really missing is that we don't (at least I don't) have a clear sense : where what type of docs should go. Some in javadocs, some on the wiki, almost : none on the forrest site. Javadocs work great since they are attached to : sources and get included in releases. But solr's users are not all javadoc : readers (nor should they be). Solr docs really should be in a non java : specific context.
Once upon a time the plan (or at least my plan) was that how/what/why documentation for provided plugins (dismax, fieldtypes, analysis factories, etc...) would live (close to the code) in class level javadocs -- our users may not be javadoc readers, but we could link straight to the good pits from user centric forrest based "overview" pages. The wiki would be a way for users to write "tips and tricks" type docs. But things didn't really work out that way ... as simple as forrest is to use to generate pages, it's not the most freindly tool to add and organicly grow a set of documentation ... plus we made the decision early on to start a lot of docs on the wiki "to flesh them out and make them easier to tweak" with the intention of eventually migrating them to "official" forrest docs .... except that we didn't know then what we know now about the legal issues -- but even before we knew about the legal issues, no one ever really had the inclination to migrate any of the docs. 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? : 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. : 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. : 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. -Hoss
