: OK, so how about this for Solr documentation on the website:
: pseudo-versioned live docs.
:
: The docs for 4x live under
: solr/4 or solr/doc/4
:
: These docs wouldn't be strictly versioned... we would continue
: updating the docs as needed after a release.
...
: A different question is whether these docs should be included in a
: release. IMO that's not needed (and creates extra maintenance work in
: our build scripts, puts extra burden on release managers, etc).
just to be clear, you are suggesting that the canonical, authoritative
source version of hte documentation would be part of the website (under
"https://svn.apache.org/repos/asf/lucene/cms/trunk) in markdown format,
editbale via the CMS; and that these docs wouldn't be "branched and
versioned" in the same way as releases, we'd just have a "4" directory
side by side with a "3" (or "5" directory) in the same "trunk" of the
website source dir.
essentially this inverts the idea of "versioned" docs as we've thought of
it in the past -- instead of keeping the docs in svn along with the src
code, and copying a "snapshot" to the live site when we release, we'd have
continously living breathing versions of the docs for each branch that are
canonically part of hte site, and those could be snapshoted when a release
is cut.
(personally i think including snapshots of at least the raw markdown
version of the docs in each release tar ball is critically important --
but i recognize that this could easily be a question scripting an
automation and should be orthoginal to the question of where these docs
live canonically and how they are edited)
I'm suprised at how little i hate this idea.
The biggest concern i have is still about encouraging documentation
contributions from the community. With the forrest based docs, it wasn't
"trivial" for a user to help improve the docs, but it was at least
straightforward on anyplatform that supported java, and the inclusion of
the source docs in the main trunk of code development ment anyone hacking
hte code could easily hack the docs as well. Asking people who want t
ocontribute to the documentation to check out another svn working dir
probably isn't hte end of the world -- but we have to find a way to make
testing local doc builds easier and less error prone for this to be
viable.
-Hoss
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
