lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Chris Hostetter <hossman_luc...@fucit.org>
Subject Re: Changing our Wiki software?
Date Wed, 29 Feb 2012 19:35:19 GMT

: 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: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org


Mime
View raw message