Following meeting about docs

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

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.

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

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

Re: Following meeting about docs

[Noah Slater <ns...@apache.org>]

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