On May 21, 2013, at 18:55 , Noah Slater <nsla...@apache.org> wrote: > Another way of looking at this is that by moving things to the docs, you're > putting it behind a "commit bit" wall. That's appropriate in a some > instances, but not in others.
> > The wiki is open to developers, and good for collaboration, coordination, > sharing resources, drafting things, etc. It's also used as a "noticeboard" > in a few instances. This is why I think the wiki is better for project / > community level stuff. Another another way of looking at this is that we make it accessible to the GitHub-on-website-fork-and-edit-and-pullrequest instead of the shoddy wiki that everybody hates and nobody works on because the experience is so abysmal. Jan -- > > It's not just Release_Procedure I'm concerned about. I did a quick survey > of some of the top pages... > > ... But before I do the rundown, TL;DR: This seems complex. We might want > to consider each wiki page separately. > > Quick rundown: > > http://wiki.apache.org/couchdb/Weekly_News > > - This is a WIP. I actually want to move to having an index here too, where > each week's weekly news is drafted on the wiki. This would be a > collaborative effort between developers and committers. > > http://wiki.apache.org/couchdb/SourceCode > > - This is in the "would be on the website if we had one" category. > > http://wiki.apache.org/couchdb/Release_Procedure > http://wiki.apache.org/couchdb/Test_procedure > > - Both of these change quite frequently > > http://wiki.apache.org/couchdb/Release_Calendar > > - This makes no sense in the docs, because it's time-based statuses. It's > more like a notice board. > > http://wiki.apache.org/couchdb/Committer_Election_Process > http://wiki.apache.org/couchdb/PMC_Election_Process > http://wiki.apache.org/couchdb/Community_Guide > > - Both WIPs. Will flesh these out over time. More of the "how we work" / > process stuff. Expect there to be more of this over time. Having it on the > wiki lets me do this WIP stuff without worrying about lots of messy stuff > ending up in our manual. > > http://wiki.apache.org/couchdb/Roadmap_Process > http://wiki.apache.org/couchdb/Merge_Procedure > > - More examples of docs that are not official, but are being *drafted* on > the wiki. These would not be appropriate to include in the docs at this > stage. > > http://wiki.apache.org/couchdb/CouchDB_in_the_wild > http://wiki.apache.org/couchdb/People_on_the_Couch > http://wiki.apache.org/couchdb/CouchDB_tools > > - This is more of the "noticeboard" type page. I see this as a way for the > community to collaborate, communicate, etc. It wouldn't be appropriate to > move this information to the manual or the developer handbook. > > http://wiki.apache.org/couchdb/CouchDB_meetups > > - Another one of the noticeboard type pages. This is time-based > information, and is good on the wiki for collaboration. Would not be > appropriate in the docs. > > http://wiki.apache.org/couchdb/Getting%20Help > > - Not sure about this. This is of the "would be on the website if we had > one" category. If we put this in the docs, would it be obvious for people? > How would you find it? Seems like a good case for being on the wiki? > > 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 > > - Good candidates for the docs. > > http://wiki.apache.org/couchdb/Development > > - Some good candidates here for the developer manual. > > http://wiki.apache.org/couchdb/Build_Process > > - This seems like a collaborative page. By which I mean, seems like the > sort of thing to keep out of the docs. The wiki is sometimes used as just a > scratch pad for people to share ideas in an informal way. > > http://wiki.apache.org/couchdb/Documentation > > - Another one that looks like a temporary collaboration page. Could > probably do with an overhaul. After the update, this would probably be in > the "would be on the website if we had one" category. > > http://wiki.apache.org/couchdb/ContributorWorkflow > > - Good candidate for the developer manual? > > http://wiki.apache.org/couchdb/Related_Projects > > - More of a noticeboard type page. Should be on the wiki for collaborative > purposes. > > > > > 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. >> >>> 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. >> >> Note though that Release_Procedure, while totally applicable to a >> developer handbook, doesn’t have to migrate today if you prefer that. >> If so, I’d suggest we just put a link into the developer handbook that >> points to the wiki. >> >> Does that make sense? >> >> Jan >> -- >> >> >>> >>> >>> >>> On 21 May 2013 16:00, Jan Lehnardt <j...@apache.org> wrote: >>> >>>> >>>> On May 21, 2013, at 15:27 , Noah Slater <nsla...@apache.org> wrote: >>>> >>>>> Actually, I prefer that project documentation be kept on the wiki. >>>>> >>>>> The docs that we have in the source are the "CouchDB Manual" (as I >>>>> have titled it), and I see them as a reference work for CouchDB itself. >>>>> Setting it up, configuring it, using it, etc. >>>>> >>>>> I see the wiki as more a place for the project / community to document >>>> and >>>>> organise itself. Consider that our homepage is a single HTML page. Most >>>> of >>>>> what we'd usually have on a website was moved to the wiki. So, I'm >>>> talking >>>>> release process, release calendar, source locations, active releases, >>>>> committer election process, PMC election process, and soon, by-laws, >>>>> community guides, etc. >>>>> >>>>> I'd like to keep this stuff on the wiki for now. >>>> >>>> I want to start a section in there that is called “The Developer >> Handbook”. >>>> The release docs would fit right in there, but this is your call >>>> ultimately, >>>> maybe we can have a pointer to the wiki from the docs/ then? >>>> >>>> Jan >>>> -- >>>> >>>> >>>> >>>> >>>>> >>>>> >>>>> On 21 May 2013 13:20, Jan Lehnardt <j...@apache.org> wrote: >>>>> >>>>>> On 21.05.2013, at 11:37, Dirkjan Ochtman <dirk...@ochtman.nl> wrote: >>>>>> >>>>>>> On Tue, May 21, 2013 at 11:33 AM, Jan Lehnardt <j...@apache.org> >> wrote: >>>>>>>> It is all documented here: >>>>>> http://wiki.apache.org/couchdb/Release_Procedure >>>>>>> >>>>>>> Oh, good. We should definitely pull stuff like that into a developer >>>>>>> chapter of the docs, IMO. >>>>>> >>>>>> Go for it :) >>>>>> >>>>>> I think we have a rough consensus on moving most of the wiki into the >>>>>> docs. Anyone, feel free to act on this! >>>>>> >>>>>> Jan >>>>>> -- >>>>>> >>>>>> >>>>> >>>>> >>>>> -- >>>>> NS >>>> >>>> >>> >>> >>> -- >>> NS >> >> > > > -- > NS
