On 30.03.2008, at 17:00, Noah Slater wrote:
* I have updated all the source documentation to use Markdown
following
Chris's changes for the CouchDB incubation site.
What source documentation is that?
AUTHORS, BUGS, DEVELOPMENT, NEWS, NOTICE, README, THANKS,
TROUBLESHOOTING
Wow, at some point the use of all uppercase filenames does get old :P.
If the original intention of the uppcasing is to draw attention to for
example reading important things such as the README file, having 8
such files (all "polluting" the root directory) is unlikely to help.
Also, I have to wonder whether keeping some of those docs purely (or
at least mostly) online would not be better. Troubleshooting, for
example, is to me a perfect example of what to best keep in the Wiki:
it can be easily extended when people run into problems that could not
be anticipated when a release was made (or when they pulled the
source). I'd prefer simply adding a link to the wiki doc to the
README. Same with BUGS and DEVELOPMENT. Merge the basics into README,
point to the web site and/or wiki for details.
* I have added the /site/publish.sh script which can be run
directly from a
source checkout on minotaur to build and publish the site.
See above, this needs to be as simple (and was) as just an `svn up`.
As far as I can tell, the site is kept here:
/www/incubator.apache.org/couchdb
Are you suggesting that this should be a Subversion checkout?
Yes.
All my publish.sh script does in run ./build.sh and rsync the files
in the local
directory tree to the above hard-coded path on the local filesystem.
And build.sh now relies on sitting next to a trunk checkout to pull in
those other files. I'd prefer it remained self-contained, at least to
the extent that you don't need to checkout both trunk and site to
regenerate the site.
As far as the devision of information, I can see the site evolving
to include
the core/official documentation (like it has now) while the Wiki is
more of a
collection of ideas/guides/thoughts/sketches etc. Again, this fits
perfectly
with the idea of including the site as part of the tarball.
I think having a mirror of the web site installed to local systems is
weird. Installed documentation, even in HTML format, is not the same
as the web site. Different audience, different purposes. There's
overlap, sure, but overlap doesn't mean the two should be the same
thing.
And I would've really preferred having this discussion before you
checked in the changes.
Cheers,
--
Christopher Lenz
cmlenz at gmx.de
http://www.cmlenz.net/
