[DOCS-142] New Documentation Review: Shell and JavaScript Interface Created: 22/Feb/12  Updated: 30/Oct/23  Due: 01/Mar/12  Resolved: 14/Mar/12

Status: Closed
Project: Documentation
Component/s: manual
Affects Version/s: None
Fix Version/s: Server_Docs_20231030

Type: Task Priority: Major - P3
Reporter: Sam Kleinman (Inactive) Assignee: Richard Kreuter (Inactive)
Resolution: Done Votes: 0
Labels: Review
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Participants:
Days since reply: 11 years, 49 weeks ago

 Description   

Before we publish the new documentation it needs some kind of technical review. The goal is to make sure that the documentation doesn't create confusion and/or provide misinformation. Any feedback big or small is very welcome, but the main purpose of this review is to make sure that there are no gaping oversights.

The best way to proceed will be to fork the <https://github.com/mongodb/docs> repository to your own github accounts, make annotations directly in the file (or make changes if you think that will be easier) and then issue a pull request and I'll merge this content into the docs repo and make the indicated changes. All of the documentation source reStructured Text. Don't worry about the specific formatting, if you're not familiar: I can answer any questions and attend to maintaining correct formatting.

While it may be tempting to make changes and do more line-by-line editing, Kyle and I have found that it may be more efficient to just add lines that begin with "TODO " and instruction between the relevant paragraphs with instructions on the required change or changes. You can also leave comments about more global issues on this ticket (or in line whatever is easier for you. If needed, I will follow up with questions as I make the revisions.

Below are the paths of several files in the repository that address the shell and JavaScript interface, and I think you'd be the best person to do this review at this time. If you won't have time to get to this, please let us know so we can reassign this ticket.

  • docs/source/reference/javascript.rst
  • docs/source/reference/mongo.rst

If you want to install Sphinx and build the documents locally you can review the docs (more or less) as they'll appear on the website, feel free. If you're having problems with getting the docs to build, tell me so I can resolve any issue with the build process and help you get setup.

– samk



 Comments   
Comment by Sam Kleinman (Inactive) [ 14/Mar/12 ]

The above commit (https://github.com/mongodb/docs/commit/8d09bc3494487a4ebbaf0d69149fcda7a264ac5b) represents the changes I've made in response to your review.

I'm going to resolve this task now, but we can open it and revisit it if you have any further comments.

Comment by auto [ 14/Mar/12 ]

Author:

{u'login': u'tychoish', u'name': u'Sam Kleinman', u'email': u'samk@10gen.com'}

Message: DOCS-142 clean up to cross referencing and build errors.
Branch: master
https://github.com/mongodb/docs/commit/05d44dfaab1df7d8cd52eb33b75fc489b7a06884

Comment by auto [ 14/Mar/12 ]

Author:

{u'login': u'tychoish', u'name': u'Sam Kleinman', u'email': u'samk@10gen.com'}

Message: DOCS-142 corrections to javascript file in response to kreuter's edits
Branch: master
https://github.com/mongodb/docs/commit/8d09bc3494487a4ebbaf0d69149fcda7a264ac5b

Comment by auto [ 09/Mar/12 ]

Author:

{u'login': u'tychoish', u'name': u'Sam Kleinman', u'email': u'samk@10gen.com'}

Message: DOCS-142 javscript formating tweak
Branch: master
https://github.com/mongodb/docs/commit/43ffaf7814ea0c21e2dc717439e67350522b6e5c

Comment by auto [ 05/Mar/12 ]

Author:

{u'login': u'tychoish', u'name': u'Sam Kleinman', u'email': u'samk@10gen.com'}

Message: DOCS-142: fixing JSON/BSON/document terminology imprecision in javascript reference
Branch: master
https://github.com/mongodb/docs/commit/6fa09a7742fb2733bb5b1eef0d14e5b1090b196c

Comment by Sam Kleinman (Inactive) [ 02/Mar/12 ]

I have a commit staged for the rest of the changes to javascript.rst to resolve the document/json issue. If you have annotations/edits staged locally, I'll hold off to push until after merging those in, otherwise I'll push later tonight/tomorrow.

Comment by auto [ 01/Mar/12 ]

Author:

{u'login': u'tychoish', u'name': u'Sam Kleinman', u'email': u'samk@10gen.com'}

Message: DOCS-142: fixing JSON/BSON/document terminology imprecision

This commit only affects non-/reference/javascript.rst incidences to
prevent possible conflicts.
Branch: master
https://github.com/mongodb/docs/commit/b432cd8ed7746c0ee26cd897b93eacee8d558185

Comment by Richard Kreuter (Inactive) [ 01/Mar/12 ]

Per request: everywhere the term "JSON" is used in the current draft, it's not really right. (Strictly speaking, you're keying in JavaScript into the shell, and the shell converts JS objects into BSON objects, a.k.a. BSON documents. Syntactically, some BSON documents can be presented in JSON syntax, but most can't, because BSON contains data types that can't be printed in JSON.)

It'd be better to call the things the database manipulates "documents", or "BSON documents" if it's important to emphasize the binary format.

Generated at Thu Feb 08 07:38:01 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.