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 16:55:52 GMT
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.

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 <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.
>
> > 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 <jan@apache.org> wrote:
> >
> >>
> >> On May 21, 2013, at 15:27 , Noah Slater <nslater@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 <jan@apache.org> wrote:
> >>>
> >>>> On 21.05.2013, at 11:37, Dirkjan Ochtman <dirkjan@ochtman.nl>
wrote:
> >>>>
> >>>>> On Tue, May 21, 2013 at 11:33 AM, Jan Lehnardt <jan@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

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