couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Christopher Lenz <cml...@gmx.de>
Subject Re: Status Update
Date Sun, 30 Mar 2008 20:02:14 GMT
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/


Mime
View raw message