Cool. For now then, I'd say we wait for an update from Couchbase before moving forward.
If people want to jot down their ideas on the wiki page I created, I think that would be productive. http://wiki.apache.org/couchdb/SourceDocumentation On Sun, Nov 27, 2011 at 7:19 PM, Jan Lehnardt <j...@apache.org> wrote: > > 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 <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 > >>>>> > >>>> > >>> > >> > >
