I agree with the sentiments from @vanilla Iâm not a knowledgeable developer but I find Couchbase documentation really difficult to understand and not intuitive at all. This compared to for instance the excellent documentation of Mongo DB or pretty good documentation of Arango DB.
The problem in my view comes from several aspects of how the documentation is done. Thereâs a lot of industry jargon that might mean something to the right person but doesnât necessarily mean something to someone else and doesnât allow them to get a sense of how the functionality might affect them or how to use it.
Hereâs an example from the documentation on Couchbase Eventing Functions âIn the Couchbase cluster, you can use the Functions to process and respond to data-changes according to an Event-Condition-Action model.â
Now, Iâm sure someone who wrote that thought they were saying something but itâs almost exclusively jargon.
What would be far better is getting into specific scenarios, âsay youâve got a remote sensor thatâs reading temperatures and posting them to the database periodically. Each temperature reading could trigger an analysis to see if the figure was abnormal by comparing it to other temperatures during the same period of the year in other years to tell if thereâs likely a fire starting. If it turns out those temperatures are abnormally high or rising too fast it could initiate an alarmâ.
Now, Iâm not even totally sure the eventing service can do that but notice how it puts it into terms that a normal person can understand.
Later in the documentation they attempt to do this by giving some examples with for instance an ecommerce store mentioning how a customer order could trigger a change in inventory levels. This gives me an idea of what I think it can do but itâs not very clear because it assumes the reader understands what it is saying. It leaves me wondering âhang on, wouldnât the order automatically decrease the inventory levels anyway? Why do I need this eventing service for a situation like that?â
Good documentation would address those questions, it might suggest something like âyouâre working with a drop shipping company in China and it can initiate a function that messages their system to reduce their available inventory count so the inventory doesnât get sold twice while your order is being processedâ.
The thing is the Couchbase documentation assumes the readers are too smart. It uses far too few examples, the examples tend to be too vague or high level, it often tries to explain it using code rather than scenarios first. For instance, I was just watching some videos where they were explaining the use of JOINs and is talking about airports and routes. But rather than explaining âwell youâve got an airport and that airport has multiple different routes flying into and out of it. Because these routes have both a destination and an origin city if you were to store them both in the destination airport and origin airport documents then if the route got updated youâd need to change it in both locations and you could risk only changing it in one and not the other and creating confusion. So instead, itâs better off to store each route as its own document and then when youâre looking up the airport and want to show all the possible routes/destinations from that airport you can reference all of the routes connected to that airport. You can do this by referencing the airport code that is common in both documents. The code would look something like thisâŚâ Then, when youâd go through the code youâd do something like underlining and explaining each part as it is described.
As it stands you can work your way through it but itâs definitely far more painful than it needs to be if someone doesnât have previous experience with it.
Something else, you need to constantly reinforce the same concepts over and over again when youâre using your own terminology. For instance, Couchbase uses the term âbucketâ to mean something very specific that isnât common in many other systems so you periodically need to remind what does the bucket refer to and point to something tangible so the person can understand.
Iâve seen a bunch of people coming from SQL in comments on videos when they encounter NoSQL saying they are lost and the concept doesnât make sense to them, which I find weird because for me NoSQL makes tons of sense but this is a good example of it. They donât get what a document is or what a collection is and therefore how it relates so you need to keep referencing over and over. Hey, imagine youâve got a row of data now pull it out and display it vertically in JSON format. Boom, youâve got your document. Ok, so that document you can add to a collection, just like how you can have many rows on a table. Etc.
I was reading over the documentation on creating Views for queries, what a nightmare, not intuitive at all. Once you get the sense of it the approach is very elegant and though I went in thinking not having collections like I was used to in other Document databases seemed like a disability I came out feeling like actually this is probably a much better way. But understanding how it works in advance is difficult and then understanding best practices to optimize is yet another complication because thereâs not enough hand holding.
Hope that helps, I really love what Couchbase has built, itâs one of the coolest database products out there and keeps getting better more so than many competitors but I also notice when I talk to people they are saying âIâd like to recommend Mongo DB or Cloud Firestoreâ and why? Because those guys make it really easy to understand they are super start-up and developer friendly but it doesnât need to be.