Mailing-List: contact dev-help@couchdb.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@couchdb.apache.org
MIME-Version: 1.0
In-Reply-To: 
 <CAPkS=XNx8OfwmFWumjJQWhH2PLGWaRWfzOUSO6p2PuvNztCMMg@mail.gmail.com>
References: 
 <CAPkS=XN_uT26yyDzg62Jm1+KoFYwMeLnsoySFb7NE1J+V7r-0A@mail.gmail.com>
	<CAKmKYaBfe74afjxha0cqmoGg2g4NCwvB3Mc6R1ktcKagyqy+og@mail.gmail.com>
	<CABvT1DHB5yUpGqgK_GycmrfvrLHFuPcyM95Ru9tYvtNXd0RGkA@mail.gmail.com>
	<CAPkS=XNx8OfwmFWumjJQWhH2PLGWaRWfzOUSO6p2PuvNztCMMg@mail.gmail.com>
Date: Sat, 18 May 2013 16:40:04 +0100
Message-ID: 
 <CAPaJBx7wivs8gZ8Bepa5BjJSVGiSVbkY7FwUvYWjcuFt5MY=DA@mail.gmail.com>
Subject: Re: wiki choice: moinmoin vs confluence
From: Noah Slater <nslater@apache.org>
To: "dev@couchdb.apache.org" <dev@couchdb.apache.org>
Content-Type: multipart/alternative; boundary=20cf303f6e2cd2ca5204dcffe989

--20cf303f6e2cd2ca5204dcffe989
Content-Type: text/plain; charset=ISO-8859-1

Quick response:

1) Yes! Let's get the docs/ sorted out! Moving NEWS/CHANGES into them.
Moving CouchDB: The Definitive Guide into them. Incorporating the docs into
our merge and release procedure. Drumming up a docs team! (Dave! Dirkjan!
Alexander! All the exclamation points!)

2) We will always need a wiki. The wiki is a cool space to hash out
cookbooks, recipes  "this is what I had to do to get this working" stuff.
But also, our homepage is a marketing site. Which means that our wiki is
our website. It has page on where our source code lives, on how to
contribute, on how our releases work, how our community works, etc.

3) MoinMoin is a POS. I would be +1 on a migration to Confluence. As much
as Confluence is also a POS, it's a lesser of two evils, and it presumably
has better integration with JIRA. Having said that, I don't think this is
critical. That is, we have bigger problems/ideas to tackle. But also, I can
see that this is a "nice to have".

On that note, if somebody wants to step forward and say "I think Confluence
is a good idea, and I am prepared to move all of our content to it" then I
would be in support of that.

I would hope for the following:

* The migration is also a "pass" over the content to tidy it up and
restructure it a bit.
* The migration identifies anything that should be in the docs (i.e.
CouchDB documentation vs. project documentation) and better yet, actually
moves that content over the to docs, even if it's only to a scratch pad or
in a "wiki-docs" branch or something.
* That this effort, or rather, the person or people involved in this
effort, form our inaugural "wiki team". That is. We've had the concept of
teams for a while now, and I think Jason is going to make a proposal on
this topic soon. But a "team" in this context could simply be a group of
folks who say "I care about the wiki and I will tend to it semi-regularly".


On 17 May 2013 19:48, Paul Okstad <pokstad@gmail.com> wrote:

> >
> > I'd prefer to have quality docs in the source code / .rst files if
> > possible. Wikis are ok for evolving stuff but if it's actually usage of
> > CouchDB proper, in the source is the way to go. You get history directly
> > tied to source code / release versions for free too.
> >
>
> I love having the manual acessible from Futon in 1.3. Definitely a good
> idea for official API documentation to be stored with source. Confluence
> would be better for hosting end user written informal docs (e.g. stuff
> currently covered by the CouchDB Guide).
>
> Anybody can contribute to the ASF CouchDB blog by simply sending an
> > attached markdown file along, jira ticket, to the dev@ mailing list, or
> > via
> > git.
> >
>
> Sounds like a good way to submit immutable content for ASF members, but
> what about "living" blog entries that can be easily updated as time goes
> forward? Confluence allows you to easily maintain a chronological listing
> of blog entries parallel to structured wiki content and each entry can be
> tagged with labels so that you can cross reference blogs automatically from
> structured wiki content (e.g. I can add a "changes_feed" label to my blog
> entry on how to create a chat room CouchApp, and then back in the HTTP API
> section for the _changes feed you can automatically list articles related
> to the "changes_feed" label).
>
> Also, just listening to the whole process of submitting a blog entry makes
> it really clear that this is a process very specific to ASF and not known
> to your typical CouchDB community person. There's a lot of valuable
> documentation out there written by end users of CouchDB that would benefit
> from being hosted centrally and in a user friendly way.
>
> There's even some workflow stuff if we wanted to show that
> > a page was +1'ed by a committer. It'd be good to get a sense from ASF
> > Infra all the plugins currently available, and their openness to new
> > plugins.
> >
>
> The +1 ability is a good example of how the social aspects of Atlassian can
> help a collaborative project like this. Also, a good plugin to check on
> would be Gliffy, which is great for illustrative purposes. It lowers the
> barrier to creating diagrams that are also version controlled.
>
> Have you seen the new Sphinx-based docs?
> >
>
> Sphinx is a great tool, but it still doesn't have the user friendliness or
> social features of Confluence. What I'm suggesting is a way to get more
> involvement from less-technical members of the CouchDB community. Sphinx
> could be a great way to host official "strict" docs, but Confluence would
> be a great way for non-couch-devs to provide use cases and higher level
> documentation to total noobs. While I miss the markup removed in
> Confluence, it has lowered the barrier to people who don't know the mark up
> differences from wiki system to wiki system. It might be useful to have a
> dual-wiki approach: one for strict API docs tied to source code and one for
> casual and end user provided articles. I'm really surprised that the
> current source code hosted documentation isn't linked to from the wiki.
> Also, maybe I'm just talking too much :D
>
> On Thu, May 9, 2013 at 3:53 AM, Robert Newson <rnewson@apache.org> wrote:
>
> > I'm definitely in favour of building up the docs/ effort to replace
> > the wiki as *the* place to find out how couchdb works. I can't quite
> > picture what will be left of the wiki when that's achieved. I guess
> > the pages where we list contributors and couchdb-based projects, but
> > not too much else.
> >
> > I'm -0.9 (see http://www.apache.org/foundation/voting.html) on
> > switching to Confluence. The choice of wiki technology is a tiny
> > factor, in my opinion. No wiki is useful without active maintenance.
> > Unless there's a horde of editors just waiting for the switch before
> > they'll help out, I think it's a distraction from the real issue.
> >
> > B.
> >
> > On 9 May 2013 11:46, Dirkjan Ochtman <dirkjan@ochtman.nl> wrote:
> > >> Anyway, I'm really excited about CouchDB and I really want to
> > contribute to
> > >> the global documentation out there, but MoinMoin ain't making it
> easy. I
> > >> really think that a move to a better documentation tool could be a
> huge
> > >> push to CouchDB's adoption. Thanks for listening.
> > >
> > > Have you seen the new Sphinx-based docs? I think they're a huge
> > > improvement over both the wiki and the book drafts. Personally, I
> > > think it would make a lot of sense to invest more time in those,
> > > rather than moving wiki content around. We could port wiki content
> > > that's missing from the docs to reST so it gets included in every
> > > CouchDB release (where it's easily accessible through Futon).
> > >
> > > I think the biggest problem with the wiki is that wikis require a lot
> > > of what I tend to think of as "gardening" to make them easy to
> > > navigate. I don't think MoinMoin is the larger problem here (though I
> > > tend to agree that it's pretty unattractive).
> > >
> > > If we want to go one step further with reST, it would even be possible
> > > to have similar handling for the blog. I use Pelican for my personal
> > > blog and it uses reST as well. We could have a directory "blog" in the
> > > tree somewhere where people can collaborate on blog entries which
> > > subsequently get published to the interwebz.
> > >
> > > Cheers,
> > >
> > > Dirkjan
> >
>
>
>
> --
> Paul Okstad
> (310) 359-0767
>


-- 
NS

--20cf303f6e2cd2ca5204dcffe989--