My documentation demands

[Nathan Vander Wilt <na...@calftrail.com>]

I followed along with the CouchDB Summit minutes. This was discussed and I know the summitters intend to bring this (and other) discussions to this mailinglist. Allow me to jump the gun on one particular issue: documentation.


# The rules

1\. Any given checkout of the CouchDB repo should include an honest attempt at always-current, complete, authoritative documentation
1b\. Each official release of CouchDB should include a link to a permanently online version of that version's corresponding docs

2\. Everything else (books, blogposts, comments in /etc/couchdb, notes on JIRA tickets, feature developer's admirable gist.github.com notes, random lines of advice from the un-archiveable IRC channel pasted into other projects' issue trackers, UTSL, even Release Notes and an "official" wiki…) is all great — hooray internet! — but does. not. count.


# Why this matters

For whatever reason all the great material that is being written up around CouchDB has weak "Google Juice" — for every search term I get a few really really old blog posts from people using CouchDB in 2008, a random crash report or three, the relevant but high-level chapter in the CouchDB book, and rarely rarely rarely any results from Apache's mailinglist archives or JIRA or Couchone's old documentation or blog posts.

For example, I just spent waaaaay too much time trying to figure out if I could filter _changes by a map function, and how. This is just one example; I've been through this story at least a dozen times before.

After at least 5 minutes of Googling various fruitless search terms, I finally found record of an IRC conversation that encouraged me, in another projects issue tracker: <https://github.com/janmonschke/backbone-couchdb/issues/15> 

That let me know, yes, CouchDB should have that feature and it was added in (erroneously) version 1.1. Hooray! But I still have no idea what its "keyword" is so I'm not much better off Googling.

I repeatedly scour the 1.1 release notes and documentation, but no dice.

I go back to random google searches on whatever synonyms I can think of for "filter" "changes" "view" "map" and capital-f-Finally conjure up a mailing list thread re-hosted by one of those archive sites with the ads. But now I can carefully Google for an exact quote and get to the discussion. <http://mail-archives.apache.org/mod_mbox/couchdb-dev/201011.mbox/%3CAANLkTikjoXkPVU5yGTZ-rwKi+ppDD+3yz8w3BcZopO1D@mail.gmail.com%3E>

Okay, now I know that I'm looking for filter=_view and manage to find the JIRA ticket: https://issues.apache.org/jira/browse/COUCHDB-987

Aha! It was actually released in 1.2. I *just* read those release notes, how'd I forget that? Oh, it only got a very casual mention within https://blogs.apache.org/couchdb/entry/apache_couchdb_1_2_0 and of course since there is no documentation there was no way the note could be linked to more information.

This has to stop.

Can we get Couchbase's donated documentation "source" into the code repo asap no matter what?

I don't care if they used Doc Format X with Toolchain Y to generate Output Format Z and that was all wrong. I think we need One True Documentation that's "wrong" and takes patches to fix, much much more than anything outside of the repo.


thanks,
-natevw