Always good when that happens.
On 21 May 2013 18:19, Jan Lehnardt <[email protected]> wrote: > On May 21, 2013, at 19:17 , Noah Slater <[email protected]> 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 <[email protected]> wrote: > > > >> > >> On May 21, 2013, at 19:02 , Noah Slater <[email protected]> wrote: > >> > >>> Also... > >>> > >>> > >>> On 21 May 2013 17:23, Jan Lehnardt <[email protected]> wrote: > >>> > >>>> > >>>> On May 21, 2013, at 17:25 , Noah Slater <[email protected]> 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
