Azure-docs: Node.js Intro to DocumentDB can be confusing & convoluted

[graham-sportsmgmt]

This is not a straightforward way to learn how to use the documentdb node sdk, with all the use of internal objects and self/this references that node developers don't use as a standard. The mongodb and dynamodb tutorials are much simpler and help users of all levels come up to speed quicker. Please remove the "opinionated design" and just show how the sdk works.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: f7ad84a6-f6b6-dd21-e7be-865d922c7ad4
• Version Independent ID: 1f5a0315-d7b4-3f8f-3b1d-ae90c807859d
• Content
• Content Source
• Service: cosmos-db

[amanarneja]

Thanx for the feedback. I have assigned this to the author to evaluate your feedback and get back to you.

cc @tysonn so that you can keep track of this issue.

[graham-sportsmgmt]

I'd be happy to contribute or assist with a new tutorial if you like. We have been using documentdb in production for nearly a year.

[mimig1]

in-process

[mimig1]

Thanks for your feedback @graham-sportsmgmt. Do you think it would be better to remove the article until a better replacement is available, or leave this online until the better replacement is available? And are you interested in making improvements to this tutorial, or would you suggest starting fresh? We've received similar feedback not too long ago - so we realize this article needs an overhaul.

[graham-sportsmgmt]

It's one of the few documents out there, it's probably best to leave it in place for now.

I'd recommend that it be replaced fresh with a simple node/express/pug step by step tutorial that illustrates CRUD. That is where most people want to start with documentdb.

[mimig1]

What do you think about the code provided in this github sample - https://github.com/burkeholland/cosmos-express-es6? It refactors the code in the current tutorial with Promises and ES6 and has CRUD for the database and collection. We're thinking about using that code as the basis for the new tutorial. Thoughts?

[graham-sportsmgmt]

It's still convoluted and someone who is learning how to use the sdk still has to trace back through multiple levels of objects and files to figure out what is going on. Promises and ES6 would be the very last things I'd add in order to make the introductory tutorial more friendly.

I believe that the goal here would be to help the maximum number of people learn the essentials of the SDK in the shortest possible time. More intermediate and advanced tutorials would be more than welcome, but the core starting point needs work first in my opinion.

[mimig1]

Ok, thanks for the candid feedback. I imagine you've seen this tutorial? https://docs.microsoft.com/en-us/azure/cosmos-db/sql-api-nodejs-get-started What are your thoughts on it?

[graham-sportsmgmt]

I had seen an earlier version. it's not bad.

Take a look at this: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStarted.NodeJs.html

[mimig1]

Thanks for the feedback. In what aspect would you be interested in contributing to the new article? We can draft the content and you work with you get your feedback early, or if you wanted to draft something and submit it in a PR we can work with you that way. Let me know your preference.

[graham-sportsmgmt]

I'd like to draft something and submit in a PR, please advise on where/how you'd like me to do that.

Thanks!

[mimig1]

Great! You can use the raw markdown from the original file as a guide - https://raw.githubusercontent.com/MicrosoftDocs/azure-docs/master/articles/cosmos-db/sql-api-nodejs-application.md. You can update the metadata at the top of the article as needed, but it will largely stay the same. You can use the heading structure as a guide as well. Once you have a draft ready, you can send submit a pull request (PR) to this repo. You can use the github.com UI, or fork the repo, clone locally, and create a working branch - whatever you're comfortable with. Once you submit the PR I can work with you to get it reviewed by the product group and get it published.

[mimig1]

Following up - @graham-sportsmgmt, we are using git issues to triage feedback from the community. For fixes that are non-immediate, we are closing the issues once the triage has occurred and the long term plan has been identified. So I’d like to suggest that we close this issue, and I will work with you independently to incorporate your updated tutorial into the documentation. Does that work for you?

[graham-sportsmgmt]

That will work for me. I can be reached at [email protected]. Thanks!

[Jeremywhiteley]

How about including authentication and using resource tokens in an example? There isn’t one example using authentication except for Xamarin and again it doesn’t follow best practices either. I am so frustrated that you don’t publish real world examples.

[graham-sportsmgmt]

Jeremy, I agree with this too. I just opened this topic to collect topics for tutorials/articles that we'd like to see beyond the basics:

https://github.com/MicrosoftDocs/azure-docs/issues/5175

[prashanthmadi]

was there any outcome from this issue ?

I was going through docs and was totally lost with self and other things as highlighted by @graham-sportsmgmt

Documentation for Documentdb sdk should be improved ... It's good that we have a doc explaining with example app.. but there should be one on basics too ..

Lets say if i already have collection/database.. how do i just add a document to it ? There is no straightforward answer to this.

[graham-sportsmgmt]

I just submitted an initial draft tutorial to the MS team, I think it will clear up a lot.

[prashanthmadi]

Thanks @graham-sportsmgmt

[mjugger]

Sooo I guess nothing came of this?

[graham-sportsmgmt]

I won't get into the details, but I think that the tutorial I wrote would be better off as a series of blog posts :)