On 1 May 2013 20:50, Paul Okstad <poks...@gmail.com> wrote: > Hello dev team, > > I'm following up on a brief discussion I had with the CouchDB twitter > account (my handle: @pokstad) regarding the official ASF wiki for CouchDB. > > I'm a CouchDB evangelist in both my personal projects and at my full time > job at a large engineering company (not Atlassian, lol). When I advocate > CouchDB, the main thing that becomes frustrating is the lack of quality > documentation. The CouchDB Guide by J. Chris Anderson was a great > introductory resource, but the current draft version is so out of date that > it's not a great resource to introduce new users to couch IMO. > > I believe part of the reason for the lack of documentation is the lack > luster moinmoin wiki. Obviously, being a huge fan of CouchDB I am a big > proponent for OSS, but I feel that the moinmoin wiki is hurting the CouchDB > community. It's a very unattractive interface and it is difficult to > navigate the wiki. While these concerns may not be huge issues for the > person(s) who chose this wiki, I believe it raises a barrier to entry for > less-technical potential contributors (e.g. myself). > > CouchDB is also about a community of developers and users, and Atlassian > has been working very hard on making the current Confluence release more > and more social. I know this sounds like a tired buzzword, but consider > this: Atlassian supports blog entries for users of a wiki space. Right now, > there are many couchdb blog entries scattered about the web on many > different managed sites. What if members of the CouchDB wiki space were > permitted to write blog entries about anything they want? Not just > structured documentation, but also a well designed hub for anything couch > related. This could really unify couchdb articles. Also, the newest > confluence has support for twitter like #hashtags and @mentions that can be > used for tagging articles/pages and alerting users. > > Thanks Paul, <3 this discussion!
I'm neither for nor against it, but here's my woolly thinking: ## Real Docs 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. The ASF comments plugin works when hooked up to our docs system but I've failed to get it to appear in a usable form in the right place on the page just yet. I love markdown, am OK with rst, and hate wiki format,and loathe crappy web IDEs. ## Blog 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. I've found a simple way to pre-process these including with source-code highlighting, so it gets processed, and then manually uploaded, and with a little bit more effort this can likely be done by anybody with ASF commit privs via a single script + sanity checking. ## the Guide The rewrite and inclusion of the book into CouchDB source itself is a big task, but if Noah etc are ok for us to take the ball & run with it (IP clearance etc notwithstanding) then people can get on with it as we did for the ex-Couchbase docs. ## The wiki Suffers from the same fate as all wikis, maintainability. Same as our released .rst docs for that matter. They need tender love. > Also consider this: Confluence has a Flash/HTML5 plugin that would allow > users to collaborate on architectural drawings to illustrate CouchDB use > cases better. > > 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. > > -- > Paul Okstad > And thanks again for writing. If you (and any others) want to fix this, I'm all for assisting you to make it happen. We probably need some kind of "document strategy" which sounds overkill, but probably boils down to 3 things. - where we store official content vs evolving stuff - how can we make it as easy to add/edit stuff as possible (blog, wiki, source docs, whatever) - keeping in simple and up to date Oh I've just seen Wohali's comments so, yeah, +1 to that too. Please let me know if & how can help. A+ Dave
