Mailing-List: contact dev-help@couchdb.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@couchdb.apache.org
MIME-Version: 1.0
In-Reply-To: <A1C8C914-FBBD-40DD-91FC-EDDF88A1FCDF@apache.org>
References: 
 <CAKmKYaB179aGmk13oCPGM4znOG9=p7K8AqCuD+2-vdsP3Ck4wg@mail.gmail.com>
	<CAPaJBx4NGpubbCGBEFH4GwXM53FF7tY0jDRovAUvXgW_zggWcA@mail.gmail.com>
	<CAKmKYaAwfFBijBUY3LPNBxDkgUc-p0JN6m2=9D41Tk6L1yT_+Q@mail.gmail.com>
	<CAPaJBx4NbLn3LFAGZSWiZmKV4rXZGwZkjapKs=s5egxxZu__1g@mail.gmail.com>
	<CAKmKYaCvHiyNFGmEBWn+_o0VeOtm2kvu88gCRjwhTHAcLjE-nA@mail.gmail.com>
	<BD5D6570-8BE5-4C1E-8ADE-F0E8D9208688@apache.org>
	<CAKmKYaAtWm=0EayWqNqPo7KJOZRxFx+TxNBENoGAbygC44LY_w@mail.gmail.com>
	<FF2DB319-8109-4B4D-9345-2E004B6DAB2E@apache.org>
	<CAPaJBx7YWrgaSnX1s=xfQVte7fBD8nme6-MmDQjTCQ8wFQGa1g@mail.gmail.com>
	<8A9C93F9-05A9-452F-B8FE-7815D0738226@apache.org>
	<CAPaJBx5eXPMaRPry8fW2XC5a7anEWCYirmwZT7KxaQE=awpO7w@mail.gmail.com>
	<85E83243-7828-473B-A805-9DBF955113DC@apache.org>
	<CAPaJBx5fm21gcBjLRVJjYEWhRC1X6rPj-165s+PQr8Km76CioQ@mail.gmail.com>
	<A1C8C914-FBBD-40DD-91FC-EDDF88A1FCDF@apache.org>
Date: Tue, 21 May 2013 18:17:50 +0100
Message-ID: 
 <CAPaJBx5nMePja_4x3X++OV99T+C8ROCeNmCyuuLFcE_OuqD-oA@mail.gmail.com>
Subject: Re: Getting rid of file lists in documentation Makefiles
From: Noah Slater <nslater@apache.org>
To: "dev@couchdb.apache.org" <dev@couchdb.apache.org>
Content-Type: multipart/alternative; boundary=20cf303bfb62f7f72704dd3da0fc

--20cf303bfb62f7f72704dd3da0fc
Content-Type: text/plain; charset=windows-1252
Content-Transfer-Encoding: quoted-printable

As someone who contributes to the wiki quite frequently, I'm not sure I
agree about the experience being horrendous. However, I would like it to be
easier. But this is one of many considerations.

As I say, we don't need to make any Big Decisions on this. Let's just take
things step-by-step.

Some good candidates for the docs right away:

http://wiki.apache.org/couchdb/Frequently_asked_questions
http://wiki.apache.org/couchdb/Breaking_changes
http://wiki.apache.org/couchdb/Error_messages
http://wiki.apache.org/couchdb/Troubleshooting
http://wiki.apache.org/couchdb/Known_Problems
http://wiki.apache.org/couchdb/ContributorWorkflow
http://wiki.apache.org/couchdb/Running%20CouchDB%20in%20Dev%20Mode
http://wiki.apache.org/couchdb/Source%20Code%20Repository%20Organization
http://wiki.apache.org/couchdb/Merge_Procedure
http://horicky.blogspot.ie/2008/10/couchdb-implementation.html

And then lots of really obvious stuff like:

http://wiki.apache.org/couchdb/Full_text_search
http://wiki.apache.org/couchdb/Adding_Runtime_Statistics
http://wiki.apache.org/couchdb/Tips_%26_Tricks_for_developers
http://wiki.apache.org/couchdb/couch_edocs

... And many more.

There is plenty of work here for people to get stuck in to. And I'd like to
see us move this stuff over first.

(I think because I am worried that we'll make a few new things in the docs,
forget to update them, and never bother to move the old stuff. I'd like to
see someone put in the legwork with the existing docs before we start
talking about new docs.)

For the new stuff we've been talking about. Who we are, how we work, etc,
etc, let's just stick this on the wiki as part of a drafting process. In
fact, I would be completely happy with the general idea that the wiki is
the place where we draft things. And the doc is where we migrate things as
they mature.


On 21 May 2013 18:08, Jan Lehnardt <jan@apache.org> wrote:

>
> 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=92m roughly modelling this after the FreeBSD project which has
> >>
> >> http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/
> >> (this corresponds to our =93docs/=94)
> >>
> >> 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 starte=
d
> >> 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 i=
s
> > 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 a=
re
> > 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 h=
as
> > to be permanent.
> >
> > --
> > NS
>
>


--=20
NS

--20cf303bfb62f7f72704dd3da0fc--