Re: Following meeting about docs

[Alexander Shorin <kx...@gmail.com>]

Hi Noah!

I'd created issues to track down further works on these directions:

https://issues.apache.org/jira/browse/COUCHDB-1781
https://issues.apache.org/jira/browse/COUCHDB-1782

Will try to figure out how to work with ASF git tonight and push my
changes as base for it. Sorry for delay on this question!

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


On Sun, Mar 10, 2013 at 1:31 AM, Noah Slater <ns...@apache.org> wrote:
> 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 <kx...@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