couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jan Lehnardt <...@apache.org>
Subject Re: Getting rid of file lists in documentation Makefiles
Date Tue, 21 May 2013 17:19:57 GMT
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


Mime
View raw message