Uploaded image for project: 'Couchbase .NET client library'
  1. Couchbase .NET client library
  2. NCBC-258

Improvement needed around documentation of using singleton client

    Details

    • Type: Improvement
    • Status: Closed
    • Priority: Major
    • Resolution: Done
    • Affects Version/s: None
    • Fix Version/s: backlog-2.0
    • Component/s: docs
    • Labels:
      None
    • Sprint:
      Sprint 2 - Feb 5-26 2014

      Description

      This has been coming up more and more lately. Apparently customers are not seeing or understanding the need for using a singleton client, even in their very basic testing.

      Additionally, all of the tutorial and API examples in the documentation show the creation of a client for every operation and so tend to reinforce the bad habits.

      Can we make an effort around identifying and improving the visibility of this very painful issue?

      No reviews matched the request. Check your Options in the drop-down menu of this sections header.

        Activity

        Hide
        john John Zablocki (Inactive) added a comment -

        See "Instantiating the Client" - http://www.couchbase.com/develop/net/current

        See http://www.couchbase.com/docs/couchbase-sdk-net-1.2/stage3.html in the Tutorial.

        I think that's pretty clear, no?

        Show
        john John Zablocki (Inactive) added a comment - See "Instantiating the Client" - http://www.couchbase.com/develop/net/current See http://www.couchbase.com/docs/couchbase-sdk-net-1.2/stage3.html in the Tutorial. I think that's pretty clear, no?
        Hide
        perry Perry Krug added a comment -

        Yes, I've seen both of those...but users are still missing it with wild frequency which is causing support cases to be logged and disruption to the sales process (not to mention the unknown impact to users who don't tell us they're having problems) so I'm asking for creative ways to make it a bigger deal. Even making the text on http://www.couchbase.com/develop/net/current into an explicit "note" would help call attention to it.

        What about a ".NET best practices" page? Or "troubleshooting common performance issues with .NET"?

        Show
        perry Perry Krug added a comment - Yes, I've seen both of those...but users are still missing it with wild frequency which is causing support cases to be logged and disruption to the sales process (not to mention the unknown impact to users who don't tell us they're having problems) so I'm asking for creative ways to make it a bigger deal. Even making the text on http://www.couchbase.com/develop/net/current into an explicit "note" would help call attention to it. What about a ".NET best practices" page? Or "troubleshooting common performance issues with .NET"?
        Hide
        perry Perry Krug added a comment -

        John, the customer pointed me to this page which does seem to show a client being created more often that we would normally recommend: http://www.couchbase.com/docs/couchbase-sdk-net-1.2/jsonextensions.html. I presume there are other places though I haven't looked through.

        Show
        perry Perry Krug added a comment - John, the customer pointed me to this page which does seem to show a client being created more often that we would normally recommend: http://www.couchbase.com/docs/couchbase-sdk-net-1.2/jsonextensions.html . I presume there are other places though I haven't looked through.
        Hide
        john John Zablocki (Inactive) added a comment -

        This example is meant to be a standalone, run once console app. So it doesn't actually create the client more than we would recommend. This example is a highly contrived "Hello, World" type of app. So I don't think it would make sense to include another singleton layer, when the client is only created once during the life of the app's execution. I could see how if that's the only code one read, it would not fully detail the proper usage. The right answer might be to implement a layer of abstraction over the client creation, via a factory or something similar...

        Show
        john John Zablocki (Inactive) added a comment - This example is meant to be a standalone, run once console app. So it doesn't actually create the client more than we would recommend. This example is a highly contrived "Hello, World" type of app. So I don't think it would make sense to include another singleton layer, when the client is only created once during the life of the app's execution. I could see how if that's the only code one read, it would not fully detail the proper usage. The right answer might be to implement a layer of abstraction over the client creation, via a factory or something similar...
        Hide
        perry Perry Krug added a comment -

        That's fair enough John. Maybe it's enough to make a bold note on that page to say "you should create a singleton"

        Show
        perry Perry Krug added a comment - That's fair enough John. Maybe it's enough to make a bold note on that page to say "you should create a singleton"
        Hide
        john John Zablocki (Inactive) added a comment -

        Deferring this for 1.2.8, to figure out what the best way to address client creation docs for trivial samples.

        Show
        john John Zablocki (Inactive) added a comment - Deferring this for 1.2.8, to figure out what the best way to address client creation docs for trivial samples.
        Show
        jmorris Jeff Morris added a comment - http://developer.couchbase.com/documentation/server/4.5/sdk/dotnet/managing-connections.html

          People

          • Assignee:
            jmorris Jeff Morris
            Reporter:
            perry Perry Krug
          • Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Agile

                Gerrit Reviews

                There are no open Gerrit changes