Alexander, Thank you for all of this! Very useful.
Once the release is done, I plan to come back to this thread and respond properly. Hope that's okay! Thanks! On 13 February 2013 16:39, Alexander Shorin <[email protected]> wrote: > 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. > > -- > ,,,^..^,,, > -- NS
