On Nov 27, 2011, at 13:10 , Marco Monteiro wrote: > I was under the impression that CouchBase might be available to give their > (docbook) documentation to the project so that it can be used as the > starting point. This would spare the community a lot of the work. > > Jan, is this still possible, and can it be worked out so that the > documentation > is in couchdb repo before, lets say, the end of the year?
We are working through the details, I'll update this thread when I know more. Thanks for your patience :) Cheers Jan -- > > On 26 November 2011 23:40, Noah Slater <[email protected]> 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 <[email protected] >>> wrote: >> >>> On Sat, Nov 26, 2011 at 14:42, Dale Harvey <[email protected]> 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 <[email protected]> >>> wrote: >>>> >>>>> On Sat, Nov 26, 2011 at 11:41, Noah Slater <[email protected]> >>> 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 >>>>> >>>> >>> >>
