couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Noah Slater <nsla...@apache.org>
Subject Re: Getting rid of file lists in documentation Makefiles
Date Tue, 21 May 2013 17:02:34 GMT
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. 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
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message