Noah: That one is on Jan.
On 26 November 2011 23:45, Noah Slater <nsla...@tumbolia.org> wrote: > Also, Bob, you mention Couchbase stepped in to fill this gap. > > Do you know where we can see the fruits of that labour? If licensing > permits, we might find it useful to take that as a starting point, or at > least reference the sections there as we can reference parts of the > existing wiki, while compiling this stuff. > > On Sat, Nov 26, 2011 at 11:40 PM, Noah Slater <nsla...@tumbolia.org> wrote: > >> Cool idea. >> >> Just to re-iterate, we should keep things as simple as possible for now. I >> think we can get away with maintaining a set of easy to read, easy to edit >> HTML files that are served up along with Futon. These would be kept in the >> source exactly the the current set of HTML files that make up Futon are. We >> might want to create a /_docs URL handler, but we can get to that later. >> >> I have created a wiki page: >> >> http://wiki.apache.org/couchdb/SourceDocumentation >> >> >> I suggest that we start collecting a proposed table of contents here, or >> even the actual documentation. Once we have enough to work with, I plan on >> moving it in to the source, and hooking up all the relevant parts of the >> system. Then, when all that is done, we can re-visit how we're going to >> publish this on the web, and whether or how we tie that to our release >> procedure. >> >> First things first, let's get the documentation written down, and >> collected together before we continue. >> >> I suspect a lot of it may already exist on the wiki in one form or >> another, in which case, it should be good enough to just create a section >> for it as it will appear in the final documentation, and then include a >> reference to where it can be found on the wiki. Once we migrate the >> documentation over to its final home, we can go about resolving these >> references and cleaning things up. >> >> >> On Sat, Nov 26, 2011 at 11:14 PM, Randall Leeds >> <randall.le...@gmail.com>wrote: >> >>> On Sat, Nov 26, 2011 at 14:42, Dale Harvey <d...@arandomurl.com> wrote: >>> > I will happily volunteer to work on generating html output from >>> whatever we >>> > store the documentation in, ultimately I think they should be integrated >>> > into futon, and I would request that whatever the documentation is >>> stored >>> > in, that its its reasonably easy to parse and wrangle into your own >>> output * >>> > >>> >>> You bring up an amazing point. However we ship the documentation in >>> the source, it'd be cool to install it at /_docs or something. This >>> would be straightforward. It'd be easy for futon to embed that (but it >>> wouldn't be tied to futon). I'd love if the startup message had a link >>> to the "Getting Started" guide or something. That makes it a lot >>> friendlier for someone to browse the docs after installing CouchDB on >>> a remote server. >>> >>> -Randall >>> >>> > Also volunteer to do any work on the website needing done >>> > >>> > Cheers >>> > Dale >>> > >>> > * I am currently wrestling with the otp team changing the erlang >>> > documentation format every release and breaking erldocs >>> > >>> > On 26 November 2011 22:20, Randall Leeds <randall.le...@gmail.com> >>> wrote: >>> > >>> >> On Sat, Nov 26, 2011 at 11:41, Noah Slater <nsla...@tumbolia.org> >>> wrote: >>> >> > That sounds reasonable. The sort of thing you'd get in an appendix, >>> if >>> >> this >>> >> > were a book. A blow by blow description of each CouchDB feature, >>> config >>> >> > variable, URL parameter, etc. >>> >> > >>> >> > Seeding the wiki is a problem. The documentation should live in one >>> >> place, >>> >> > and one place only. Seeding the wiki is a one time process, but both >>> the >>> >> > docs we are discussing and the wiki are living documents. It is too >>> hard >>> >> to >>> >> > keep this kind of duplication up to date, and I will go out on a >>> limb and >>> >> > say that, eventually, the disparities will cause the docs to do more >>> harm >>> >> > than good. >>> >> > >>> >> > What I'd like to propose is that we make the docs we have in the >>> source >>> >> > directly accessible on the web. >>> >> >>> >> Absolutely. The main reason I want to see docs live in the source is >>> >> so that it's easy to tie a version of the docs to a release of the >>> >> source. That way, we can look at hosting a documentation site that has >>> >> docs for each version of CouchDB. See http://nodejs.org/docs/ >>> >> >>> >> > >>> >> > How do we do that? >>> >> > >>> >> > The current CouchDB site is held in Subversion, and there is ASF >>> >> > infrastructure that mirrors this to a public location. Could we get >>> >> > something similar set up to host the contents of a specific folder >>> held >>> >> in >>> >> > Git? I don't know, but it's worth investigating. >>> >> > >>> >> > The only other option would be to host out of Git, like this: >>> >> > >>> >> > >>> >> >>> http://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=blob_plain;hb=HEAD;f=README >>> >> > >>> >> >>> >> FWIW I wouldn't mind adding a step to the release procedure to export >>> >> the docs @ some tag and push them up to the SVN site in a new folder. >>> >> It's not the most automatic and elegant thing in the world, but it's >>> >> simple and works today. >>> >> >>> >> Randall >>> >> >>> > >>> >> >> >
