> If someone wants to investigate what it would take to switch to use
> Confluence for the main site and/or the wiki i say great ... but it's
> important to keep in mind that:
> a) we need to be able to include "official" docs in releases
> b) wiki pages editable by "anyone" can't be included in releases
>
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.
Right now, where should we put the dismax parameter docs? Currently we
have it on the wiki and in the javadocs (still in DisMaxRequestHandler
even though the functionality is in DisMaxQueryParser... but maybe the
docs should go on the DisMaxParms!)
I agree changing the MoinMoin theme makes it look a lot better but it
still does not address your point a) -- If we stick with the status quo,
we don't have official docs. We also don't have any way to have clean
docs relevant to a release. Deprecated things never go away, they just
stack up.
Having read all the rules, this is my proposal:
1. We set up an "official" documentation site and use the policy that
http://cwiki.apache.org/CWIKI/ suggests under "But what if we would like
the community at large to help maintain the space?"
Anyone who has a CLA on file will be able to edit the wiki. It is not
hard to do a CLA and I am confident many in the solr community will take
the time to do it. It actually seems like a good thing to get people
into the club. They send away for a magic decoder ring.
People without a CLA can post comments on a page. Either this stays as
a comment, or someone could incorporate it into the page.
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.
3. For licensing issues, we can't do a bulk import. Nor do I think we
want to. For each page, someone with CLA needs to:
1. Make sure the content complies with ASF copyright issues
2. copy 1.3 relevant data to cwiki
3. leave 1.2 data on wiki and add link to new page
We don't have to do it all at once, and it does not need to be done by
commiters. We don't have so much that it is too daunting to think we
could get through it before 1.3 release.
4. with release 1.3, we can include a snapshot of the cwiki for official
docs. After the release, additions to the that reference trunk would
get flagged with something like <!>["1.4-dev"] that would get removed
prior to the next release snapshot.
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 good option.
sound reasonable?
ryan
