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:31:04 GMT
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 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.
>
> 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’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
> >>
> >>
> >
> >
> > --
> > NS
>
>


-- 
NS

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message