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: <143B216E-048D-4138-9C7E-155F37E853C5@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>
	<CAPaJBx5nMePja_4x3X++OV99T+C8ROCeNmCyuuLFcE_OuqD-oA@mail.gmail.com>
	<143B216E-048D-4138-9C7E-155F37E853C5@apache.org>
Date: Tue, 21 May 2013 18:31:04 +0100
Message-ID: 
 <CAPaJBx7ohBY2Myf2G4Cd2WQgmuCD8z87apJcUnkfKpeuQ0Na3g@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=047d7bd752b653217804dd3dd09a

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

Always good when that happens.


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

> On May 21, 2013, at 19:17 , Noah Slater <nslater@apache.org> wrote:
>
> > 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 t=
o
> 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%20Organizatio=
n
> > 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 lik=
e
> 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, et=
c,
> > etc, let's just stick this on the wiki as part of a drafting process. I=
n
> > fact, I would be completely happy with the general idea that the wiki i=
s
> > the place where we draft things. And the doc is where we migrate things
> as
> > they mature.
>
> we are saying the same thing.
>
> Jan
> --
>
>
> >
> >
> >
> >
> > 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 tha=
t
> >>>> 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" fro=
m
> 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 i=
s
> >> 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 statu=
s
> >> 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 i=
s
> a
> >>> little more mature, we can move the content wherever we like. Nothing
> has
> >>> to be permanent.
> >>>
> >>> --
> >>> NS
> >>
> >>
> >
> >
> > --
> > NS
>
>


--=20
NS

--047d7bd752b653217804dd3dd09a--