couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nathan Vander Wilt <nate-li...@calftrail.com>
Subject My documentation demands
Date Thu, 12 Apr 2012 23:33:56 GMT
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
Mime
View raw message