couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Alexander Shorin <kxe...@gmail.com>
Subject Following meeting about docs
Date Wed, 13 Feb 2013 16:39:22 GMT
Hi devs!

Summarized my thoughs on and after meeting about docs topic.

1. About docs articles restructuring

Motivation: current articles order is not logical. I'm in role of
newbie who never seen CouchDB before probably would have next
questions to answer:

1. What is CouchDB?
2. How to install it?
3. How to configure it?
4. How to administrate it? E.g. setup users, security features etc.
5. How to manage it? Basic API overview
6. What features it has?
7. Oh, couchapps! What is it and how it works?
8. Any plugins around or possibility to extend CouchDB?
9. Awesome! I want to dive deeper into HTTP API
10. ...and internals! I want to know how it works!
11. Troubleshooting, common problems and their solutions
12. Some glossary of common terms to easily understand other users
13. And I'd like to see also release notes and track version changes

and so on. For sure, some points need to be more detail like
Replication: there is two ways to replicate data, conflicts and their
solution, common practices and so forth. Namespaces are good thing to
use.

As the inspiration source the PostgreSQL docs may be used:
http://www.postgresql.org/docs/9.2/static/index.html

They also have articles following roughly the same mind flow.

Some implementation of this structure may be preview there:
http://kxepal.iriscouch.com/docs/1.3/index.html

[note: you may found few articles borked or empty for now - that's ok,
work in progress, I just need for placeholders to not forget things to
describe]

2. About external CouchDB based solutions

Dave wisely mentioned that is it right to take articles about CouchApp
tools in docs.

On one hand that's right since third party tools are third party, but
I suppose end user will be only happy to see all information about
CouchApps without need to Google about. Probably we may limit us there
with only top and short description of mature and stable tools and
also provide like to wiki that easily handles all actual things.

Same thing is about query servers, FTS, external auth providers and
more. This question is mostly about future plugins (Jan, I'd
understood the whole idea - it's awesome and my previous critics was
not correct at /some/ points). Mentioning them officially may only
raise overall interest to CouchDB itself and building new solutions
around it.

3. About 1.1/1.2 docs

Since initial imported docs were based on 1.1 release, it's not hard
to start track changes history from this point. The only problem is
where to keep these *.rst files since main CouchDB repo contains
sphinx docs only started from 1.3 branch?

4. About The Definitive Guide integration

What's the plan? It's very well written and designed in user friendly way.

Probably, there is need to walk through a lot of opened issues first
and up to date book to base CouchDB version (1.1 or 1.3):
https://github.com/oreilly/couchdb-guide/issues

After that define articles structure after merge and make some
migration script, especially for localized parts since sphinx used
gettext driven internationalization:

http://sphinx-doc.org/latest/intl.html

That's probably all for today(: Would be very happy to receive any
guidance about work on docs.

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

Mime
View raw message