Mailing-List: contact dev-help@couchdb.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@couchdb.apache.org
Content-Type: text/plain; charset=us-ascii
Mime-Version: 1.0 (Mac OS X Mail 6.6 \(1510\))
Subject: Re: [MERGE] 1781 Reorganize and improve docs
From: Garren Smith <garren@apache.org>
In-Reply-To: 
 <CAHdjipKj35M8hXbdw5gWoijwpbrJ78B9wne=i=SBJtvaP0n43g@mail.gmail.com>
Date: Sun, 29 Sep 2013 13:47:38 +0200
Content-Transfer-Encoding: quoted-printable
Message-Id: <5D8DC408-AB19-44AB-B547-9010D8FE66F0@apache.org>
References: 
 <CAHdjipKj35M8hXbdw5gWoijwpbrJ78B9wne=i=SBJtvaP0n43g@mail.gmail.com>
To: dev@couchdb.apache.org

Hi Alexander

This is amazing work. Thanks for all of this and thanks to everyone that =
helped with this.

Cheers
Garren

On 28 Sep 2013, at 2:48 PM, Alexander Shorin <kxepal@gmail.com> wrote:

> Hi devs!
>=20
> There was big docs merge from 1781-reorganize-and-improve-docs branch
> into the master branch. What's happened?
>=20
> =3D=3D=3D Changes
>=20
> - New homepage. Looks a bit Pythonic, but less confusing as huge TOC
> tree does and this is temporary solution until redesign
> - Better introduction into CouchDB
> - Base installation guides
> - Rewritten HTTP API reference
> - Complete configuration reference
> - Query server protocol definition
> - Replication protocol definition and conflicts resolution
> - Easy PR via GitHub from ReadTheDoc service
> - Rich guide to views and others design functions
> - Reserved section for Fauxton docs
> - Maintenance routines: compaction, security, performance, backups and
> others everyday routines
>=20
> =3D=3D=3D Source directory layout (share/doc/src/)
>=20
> - api
> HTTP API reference grouped by target resource: server, database,
> document and design document.
>=20
> - config
> Configuration reference grouped by propose: auth contains every
> section that tweaks authentication routines (admins, couch_http_auth,
> oauth), http - everything for HTTP layer (httpd, ssl, vhosts) etc.
> This chapter not only for config options descriptions, but also for
> guides about how configuration things are works or need to be setted
> up (see ssl and admins).
>=20
> - couchapp
> Need to admit, that CouchApp term is de-facto notable and defines
> self-hosted applications by CouchDB. This chapter is about design
> documents, design functions and how to use them effectively in real
> world. I called it couchapp instead of ddoc or something because,
> actually and suddenly, CouchDB doesn't ships with any tools to manage
> and develop design documents in the Relax way. To make something
> simple it's ok to go with Futon, but for real apps you will eventually
> use couchapp or erica project. Hope someday erica will be a part of
> CouchDB and there we can set more stuff about it.
>=20
> - cve
> CVE information for referencing from release notes and not only.
>=20
> - fauxton
> Fauxton docs. How to build, use, make addons, tweak, manage and so on.
> Currently there just imported readme and addons stuff, but hope to see
> Fauxton api and docs there
>=20
> - install
> Installation guides for various OS
>=20
> - intro
> Introduction into CouchDB. Where users meets with every basic bit of
> CouchDB. Mostly based on Guide to CouchDB content.
>=20
> - maintenance
> Is about how to make CouchDB existed instance feel live and well.
>=20
> - query-server
> Query server related stuff for developers.
>=20
> - replication
> All about replication.
>=20
> - whatsnew
> Release notes.
>=20
> Reversed for TODO:
> - dev: CouchDB internals for developers. How it works, how to hack it,
> file formats, modules API, extending etc. Erlang users oriented stuff.
> - thirdparty: Third-party projects. Do we promote active, stable,
> popular and useful projects that improves CouchDB experience like
> Erica, CouchDB-Lucene, ElasticSearch, Geocouch etc.?
> - tutorial: While the intro chapter is about introduction and overview
> of CouchDB, tutorial will be the functional step-by-step guide focused
> on meeting API by using implementation of some single tutorial project
> as an example.
>=20
> =3D=3D=3D New API Reference Syntax
>=20
> Check out for an example:
> =
https://git-wip-us.apache.org/repos/asf?p=3Dcouchdb.git;a=3Dblob;f=3Dshare=
/doc/src/api/document/common.rst;h=3D6687ebce090d4f477371234c89e93c5da62bf=
72b;hb=3DHEAD#l65
>=20
> Request items are marked with `<` prefix, response one - with `>`.
> Certainly, any prefix is omitted for things that are used only in
> request (query params) and response (HTTP code). To simplify reading,
> all endpoints descriptions are written in the next format:
>=20
> <request headers
> query parameters
> <request payload
>> response headers
>> response body
> http status code
>=20
> =3D=3D=3D Covers around 20 issues
>=20
> COUCHDB-906: Please offer offline downloadable documentation
> COUCHDB-1168:The multipart API is not documented
> COUCHDB-1254: Document design and view options
> COUCHDB-1538: Actually explain configuration options in configuring =
[reference]
> COUCHDB-1539: Write some documentation on (writing) views [views]
> COUCHDB-1540: Expand view documentation in reference (skipping and
> grouping) [api/design]
> COUCHDB-1543: Fill out db maintenance reference (?) [api/dbmaint]
> COUCHDB-1544: Fill out authentication reference [api/authn]
> COUCHDB-1545: Document missing APIs [api/database]
> COUCHDB-1546: Add table with list of APIs [api/design]
> COUCHDB-1657: View Server description does not explain how Update
> Handlers must be implmented
> COUCHDB-1781: Reorganize/improve docs articles
> COUCHDB-1820: Collation not in official documentation
> COUCHDB-1822: Authentication (particularly _users database) not
> adequately covered in official documentation
> COUCHDB-1823: Automatic compaction not in official documentation
> COUCHDB-1824: Official documentation of replication algorithm?
> COUCHDB-1847: Automatic compaction not in official documentation
> COUCHDB-1849: View generation options not in official docs
> COUCHDB-1850: Documentation missing view emit _id/_rev tricks for
> ?include_docs=3Dtrue details
> COUCHDB-1857:_changes API reference doesn't mention the eventsource =
feed
> COUCHDB-1858: X-Couch-Full-Commit is not mentioned in _bulk_docs API
> COUCHDB-1864: Use sphinx-httpdomain for HTTP API reference
> COUCHDB-1892: Documentation for POST /db/_bulk_docs needs TLC
>=20
>=20
> =3D=3D=3D External stuff
>=20
> - Modified sphinx-httpdomain extension
>  =
https://github.com/apache/couchdb/blob/1781-reorganize-and-improve-docs/sh=
are/doc/ext/httpdomain.py
>  No forward compatibility with mainsteam: we're using own, shorted
> and nicer syntax.
>=20
> - CouchDB: The Definitive Guide
>  Chapters: 1-9, 16, 17(merged with wiki article), 21, 22, 24 =
(partially)
>=20
> - Joins in CouchDB
>  http://www.cmlenz.net/archives/2007/10/couchdb-joins
>=20
> - Externals API
>  http://davispj.com/2010/09/26/new-couchdb-externals-api.html
>=20
> - Replication protocol
>  http://www.dataprotocols.org/en/latest/couchdb_replication.html
>=20
> =3D=3D=3D Deprecates and/or supersedes next Wiki pages
>=20
> - http://wiki.apache.org/couchdb/Introduction
> - http://wiki.apache.org/couchdb/Installing_on_FreeBSD
> - http://wiki.apache.org/couchdb/Installing_on_OSX
> - http://wiki.apache.org/couchdb/Installing_on_Gentoo
> - http://wiki.apache.org/couchdb/Building_from_source_on_Windows
> - http://wiki.apache.org/couchdb/Building_The_Source_On_Nix
> - http://wiki.apache.org/couchdb/Verify_and_Test_Your_Installation
> - http://wiki.apache.org/couchdb/Getting_started_with_Futon
> - http://wiki.apache.org/couchdb/Technical%20Overview
> - http://wiki.apache.org/couchdb/Using_Views
> - http://wiki.apache.org/couchdb/Introduction_to_CouchDB_views
> - http://wiki.apache.org/couchdb/HTTP_view_API
> - http://wiki.apache.org/couchdb/EnableErlangViews
> - http://wiki.apache.org/couchdb/CouchIn15Minutes
> - http://wiki.apache.org/couchdb/Reference
> - http://wiki.apache.org/couchdb/Complete_HTTP_API_Reference and every
> page it references
> - http://wiki.apache.org/couchdb/Performance
> - http://wiki.apache.org/couchdb/URI_templates
> - http://wiki.apache.org/couchdb/HTTP_status_list
> - http://wiki.apache.org/couchdb/Replication
> - http://wiki.apache.org/couchdb/Compaction
> - http://wiki.apache.org/couchdb/Runtime_Statistics
> - http://wiki.apache.org/couchdb/Virtual_Hosts
> - http://wiki.apache.org/couchdb/ExternalProcesses
> - http://wiki.apache.org/couchdb/Setting_up_an_Admin_account
> - http://wiki.apache.org/couchdb/HTTP_Bulk_Document_API
> - http://wiki.apache.org/couchdb/HTTP_database_API
> - http://wiki.apache.org/couchdb/HTTP_view_API
> - http://wiki.apache.org/couchdb/Rewriting_urls
> - http://wiki.apache.org/couchdb/Introduction_to_CouchDB_views
> - http://wiki.apache.org/couchdb/CommonJS_Modules
> - http://wiki.apache.org/couchdb/View_collation
> - http://wiki.apache.org/couchdb/View_server
> - http://wiki.apache.org/couchdb/Built-In_Reduce_Functions
> - http://wiki.apache.org/couchdb/Formatting_with_Show_and_List
> - http://wiki.apache.org/couchdb/HTTP_Document_API
> - http://wiki.apache.org/couchdb/Configurationfile_couch.ini
> - http://wiki.apache.org/couchdb/Breaking_changes
> - http://wiki.apache.org/couchdb/How_to_page_through_results
> - http://wiki.apache.org/couchdb/How_to_enable_SSL
> - http://wiki.apache.org/couchdb/EnableErlangViews
> - http://wiki.apache.org/couchdb/Performance
> - http://wiki.apache.org/couchdb/CORS
> + may be some others, but I was unable to reach them in three clicks
> from main page (I suppose such pages aren't popular and heavy
> outdated)
>=20
> =3D=3D=3D What this merge does not?
>=20
> Docs are still not provides fluid content that allows reader to
> incrementally meet with CouchDB and increase his knowledge about step
> by step like Guide to CouchDB does. Currently they looks as collection
> of independent articles that was written by different people using
> different style and mostly usable as reference material, not good
> reading on rainy evening sitting on the couch before the fireplace.
> But whoever reads the FM?(:
>=20
> =3D=3D=3D What's next?
>=20
> - Practical tutorial
> - Troubleshooting
> - More internals
> - More installation guides
> - Better articles flow
> - Redesign to match site/fauxton style
> - Nicer and printable PDF build (yes, currently you better to print
> single-paged html file as PDF from your browser)
>=20
> but all this is for another commits and not for another long-living
> feature branch (:
>=20
> --
> ,,,^..^,,,