incubator-couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Paul Okstad <poks...@gmail.com>
Subject Re: wiki choice: moinmoin vs confluence
Date Fri, 17 May 2013 18:48:27 GMT
>
> 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

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