couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Noah Slater <nsla...@apache.org>
Subject Re: Following meeting about docs
Date Sat, 09 Mar 2013 21:31:19 GMT
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 <kxepal@gmail.com> 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

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message