couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jan Lehnardt <...@apache.org>
Subject Re: Getting rid of file lists in documentation Makefiles
Date Tue, 21 May 2013 17:08:19 GMT

On May 21, 2013, at 19:02 , Noah Slater <nslater@apache.org> wrote:

> Also...
> 
> 
> On 21 May 2013 17:23, Jan Lehnardt <jan@apache.org> wrote:
> 
>> 
>> On May 21, 2013, at 17:25 , Noah Slater <nslater@apache.org> wrote:
>> 
>>> I think the idea of a "Developer Handbook" is a good one.
>>> That's separate from a "CouchDB Manual" though.
>> 
>> I’m roughly modelling this after the FreeBSD project which has
>> 
>> http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/
>> (this corresponds to our “docs/”)
>> 
>> and
>> 
>> http://www.freebsd.org/doc/en_US.ISO8859-1/books/developers-handbook/
>> 
>> (and a few more).
>> 
>> So they have separate handbooks for this, and I think eventually that
>> makes sense for us as well, but I thought it was easiest to get started
>> with the developer handbook as a chapter/section in our docs/ until it
>> is substantial enough to make into its own.
> 
> 
> It's worth considering that a developer handbook is "out-of-band" from a
> release perspective.

The 1.2.0 docs would explain the view engine as it existed then, the 1.3.0
would explain the new view engine.

Of course there is a lot of docs applicable to any version, but that is
true for the HTTP API docs as well.

Jan
--



> That is, developer information is bound to release
> versions, so it makes no sense to freeze it at those points. But if you're
> putting developer handbook information into the manual, then you are forced
> to freeze it every time we do a release.
> 
> For this reason, I am inclined to believe that any developer handbook is
> kept out of the main Git repos.
> 
> 
>>> For now, let's focus on getting the manual up to scratch, and let's keep
>>> the handbook stuff on the wiki.
>>> 
>>> We can re-evaluate the situation later. I'm not married to it. :)
>> 
>> I want to start this asap because we have some thing flying around
>> elsewhere that would benefit from getting into a definite location.
>> 
> 
> Sure. But we already have a place for it: the wiki. This is the status quo.
> :)
> 
> Let's not bite off more than we can chew. The docs are very new, and we've
> not even established a merge / release procedure for making sure they are
> kept up to date.
> 
> Once the docs are a little more settled, and the dev handbook stuff is a
> little more mature, we can move the content wherever we like. Nothing has
> to be permanent.
> 
> -- 
> NS


Mime
View raw message