On May 21, 2013, at 19:17 , Noah Slater <nsla...@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 <j...@apache.org> wrote: > >> >> On May 21, 2013, at 19:02 , Noah Slater <nsla...@apache.org> wrote: >> >>> Also... >>> >>> >>> On 21 May 2013 17:23, Jan Lehnardt <j...@apache.org> wrote: >>> >>>> >>>> On May 21, 2013, at 17:25 , Noah Slater <nsla...@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
