Details

    • Type: Documentation Documentation
    • Status: Resolved
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 1.5.0
    • Component/s: Documentation
    • Labels:
      None

      Description

      Documentation articles need to reorganize to let them easily answer on newbie questions who never seen CouchDB before in logical order they raised. For example:

      1. What is CouchDB?
      2. How to install it?
      3. How to configure it?
      4. How to administrate it? [1]
      4.1 Setup users
      4.2 Security features
      4.x etc.
      5. How to manage it? Basic API overview.
      6. What features it has?
      6.1 Changes feed
      6.2 CORs
      6.3 Externals
      6.x etc. for features that may be described in single page.
      7. Replications
      7.x what it is, how it works, how to use it etc.
      8. More about couchapps [2]
      8.x what it is, how it works, how to use it etc.
      9. Extending CouchDB
      10. Complete Guide to CouchDB HTTP API
      11. Some input on CouchDB internals
      12. Troubleshooting, common problems and their solutions
      13. Some glossary of common terms to easily understand by new users
      14. Release notes and changes history to track features.

      and so on. For sure, some points need to be more detail like
      Replication: there are two ways to start data replication; conflicts and their solution; common practises for them and so forth.

      As the inspiration source the PostgreSQL docs was used:
      http://www.postgresql.org/docs/9.2/static/index.html

      [1]: I believe, that better to guide users to use Futon for the first steps instead of fighting with curl on CLI.
      [2]: Should docs promote tools like erica, kanso and other popular ones that are still been recommended on mailing lists/IRC? Question may also stands as "how much batteries to include?".
      [3]: GeoCouch, Lucene, OX_Auth, etc. and how to write your own. Same question about promotion of third party tools. On one hand they are third party, but on other they are not so much to stay aside and raising initial interest to them may provoke to create more of them.

        Activity

        Hide
        Jan Lehnardt added a comment -

        This is an excellent list. The only edit (yay bikeshed) is to put a “quick start guide” on position 0. that gets you up and running in 5 minutes and through the basics in 10 more minutes. Kind of like http://guide.couchdb.org/draft/tour.html but in good

        Show
        Jan Lehnardt added a comment - This is an excellent list. The only edit (yay bikeshed) is to put a “quick start guide” on position 0. that gets you up and running in 5 minutes and through the basics in 10 more minutes. Kind of like http://guide.couchdb.org/draft/tour.html but in good
        Hide
        Alexander Shorin added a comment -

        CouchDB config description is done: there was found a lot of interesting options that aren't mentioned in default/local ini (:

        Head: https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=commit;h=fba2826ee390d755df17d582b3da1baa98b7a45d
        Tail: https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=commit;h=11fd32aa1fa7462536cd6d1e65c7bf493af750b8

        Show
        Alexander Shorin added a comment - CouchDB config description is done: there was found a lot of interesting options that aren't mentioned in default/local ini (: Head: https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=commit;h=fba2826ee390d755df17d582b3da1baa98b7a45d Tail: https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=commit;h=11fd32aa1fa7462536cd6d1e65c7bf493af750b8
        Hide
        Alexander Shorin added a comment -

        Jan Lehnardt good point!

        Show
        Alexander Shorin added a comment - Jan Lehnardt good point!
        Hide
        Alexander Shorin added a comment -

        Fixed in 17e0b7c

        Show
        Alexander Shorin added a comment - Fixed in 17e0b7c
        Hide
        Javier Candeira added a comment -

        As a newcomer to the project, I think it's of paramount importance to have a central, frequently updated page that explains CouchDB's relationship to 3rd party projects. This comment on HN from three years ago perfectly expresses how I felt about the project when I started as a user about one year ago:

        https://news.ycombinator.com/item?id=3180712

        There should be a prominent place on docs.couchdb.org for this kind of "view of the ecosystem" article, with feature tables and frequent updates. I'd put it in point 1.1:

        1. What is CouchDB?
        1.1 Which of the many Couch*s and *ouchDBs does what?

        Newcomers are ideal for writing newcomer-friendly articles, because we know where the sticking points are for n00bs. I volunteer to write a first draft of the article outlined in this comment, though someone else should edit it for correctness/clarity.

        Show
        Javier Candeira added a comment - As a newcomer to the project, I think it's of paramount importance to have a central, frequently updated page that explains CouchDB's relationship to 3rd party projects. This comment on HN from three years ago perfectly expresses how I felt about the project when I started as a user about one year ago: https://news.ycombinator.com/item?id=3180712 There should be a prominent place on docs.couchdb.org for this kind of "view of the ecosystem" article, with feature tables and frequent updates. I'd put it in point 1.1: 1. What is CouchDB? 1.1 Which of the many Couch*s and *ouchDBs does what? Newcomers are ideal for writing newcomer-friendly articles, because we know where the sticking points are for n00bs. I volunteer to write a first draft of the article outlined in this comment, though someone else should edit it for correctness/clarity.
        Hide
        Javier Candeira added a comment -

        > Should docs promote tools like erica, kanso and other popular ones that are still been recommended on mailing lists/IRC? Question may also stands as "how much batteries to include?"

        Again, as a newcomer, I'd vote for very prominent links to pages like this:
        https://cwiki.apache.org/confluence/display/COUCHDB/Useful+utilities

        And a second page for 3rd party client API libraries.

        To recap, I think explaining what CouchDB, Couchbase, Cloudant, IrisCouch, PouchDB and TouchDB etc. have to do with each other should be in the docs, while giving people a summary of tools and API clients should be in the wiki, linked from the docs.

        Show
        Javier Candeira added a comment - > Should docs promote tools like erica, kanso and other popular ones that are still been recommended on mailing lists/IRC? Question may also stands as "how much batteries to include?" Again, as a newcomer, I'd vote for very prominent links to pages like this: https://cwiki.apache.org/confluence/display/COUCHDB/Useful+utilities And a second page for 3rd party client API libraries. To recap, I think explaining what CouchDB, Couchbase, Cloudant, IrisCouch, PouchDB and TouchDB etc. have to do with each other should be in the docs, while giving people a summary of tools and API clients should be in the wiki, linked from the docs.

          People

          • Assignee:
            Alexander Shorin
            Reporter:
            Alexander Shorin
          • Votes:
            2 Vote for this issue
            Watchers:
            5 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development