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:17:50 GMT
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’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

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