couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Alexander Shorin <kxe...@gmail.com>
Subject Re: [REVIEW] Docs update
Date Wed, 24 Jul 2013 22:44:44 GMT
Hi Filippo,

Thanks for feedback!

> I don't understand why the installation section is so much complicated. You just need
a command to install CouchDB on the most Linux distro or Mac OS X. To understand that, a user
have to read also the "Community installation guides" present in the wiki.
> Moreover, I really don't know why I should use brew to install CouchDB on Mac OS X when
it's available through MacPorts. I mean, brew is Ruby and Ruby sucks, like everyone knows.
:-) OK, brew can be an option, but why the main or the only option?

The motivation:

0. You'd like to install CouchDB
1. Probably, you had already visited
https://couchdb.apache.org/#download and found available binaries for
Windows and MacOS. So in 80% of cases you have not to build them by
your own.
2. However, these are not your OS and you'd like to see guide for it.

There are two options:

1. You google "CouchDB 1.3 install Ubuntu"
2. You just open __official__ documentation

The first way shows you a lot of guides, even video instructions on
youtube. A lot of posts about how to install CouchDB of the latest
version on Ubuntu using different ways to go. But. Why the hell I have
to use third party sources if there is __official__ documentation? Can
I trust them? Will they be available tomorrow, when I'll be at work
and will try to follow provided guides?

The second way is just to read the docs. The wiki is good place for
community and the most recent guides, but it __always__ the latest.
There is no way to fix some guide for some specific CouchDB release
without making article big. Take a look on Ubuntu guide:

http://wiki.apache.org/couchdb/Installing_on_Ubuntu

It covers many of OS versions for many of CouchDB versions and, now,
all of them out of dated and useless, but still we have to keep them
for 20% of cases when people have older OS.

That's why installation guides (from sources, using system package
manager etc.) have to be in docs.

> The documentation says: "A high-level guide to Unix-like systems, inc. Mac OS X and Ubuntu."
I really don't see the high level there, in fact it's very detailed, it teaches how-to compile
it. As final user I'm just interested to install it, I don't care about to compile things
from scratch or install dependencies, because probably yum, apt-get or port will do it automatically.

Hm...the content is from:
https://github.com/apache/couchdb/blob/master/INSTALL.Unix
I hadn't add something from myself except formatting (:

> Sincerely, I don't really think is a good idea having a wiki with the same contents of
the manual. Why not just have a good manual and remove that wiki? All the relevant wiki contents
should be assimilated into the manual to improve it and have a single start point.
> PHP does have a wiki? MySQL does have a wiki? Why don't merge the wiki with the manual,
just like you are merging BigCouch into CouchDB? :-)
> Don't tell me that everyone can contribute to the wiki, because that's not true, you
need credentials to do that, instead everyone can pull a request to modify the manual.

You got the point, but from the opposite side (: Content is moving
from wiki to docs in wiki is been deprecated in favour of docs.
Community still be able to easy contribute stuff with easy (see Edit
on Github link on sidebar) without need to request registration
permission, deal with some Moin-Moin systems etc.

In same way you could say for Guide to CouchDB: it also going to be
merged with docs, like BigCouch into CouchDB(:

--
,,,^..^,,,

Mime
View raw message