surrealdb / docs.surrealdb.com

The documentation for SurrealDB, powered by Docusaurus
https://surrealdb.com/docs/
70 stars 112 forks source link

docs: Updates to concepts, making 1.x and 2.x consistent #649

Closed matthewjnield closed 2 months ago

matthewjnield commented 2 months ago

This commit updates the 1.x and 2.x documentation, within the "Introduction" section, on the "Concepts" page ("concepts.mdx"), to eliminate some small inconsistencies between the 1.x and 2.x versions.

netlify[bot] commented 2 months ago

Deploy request for surrealdb-docs pending review.

Visit the deploys page to approve it

Name Link
Latest commit 6ed38ef83b32ea9fd3d4bdf35129f54bb0641e0e
Ekwuno commented 2 months ago

Hey @matthewjnield, Thanks for making this PR. I can see that this update only removes the comma in the first sentence, which is actually intentional, as Oxford commas are part of our style guide. Also, using a comma before a conjunction (like "and") in a list of three or more items is standard practice.

Therefore, I'll close this PR. However, please feel free to go through any of the open issues . We will be happy to get another contribution from you! 💜

matthewjnield commented 2 months ago

Hello @Ekwuno, thank you for taking the time to review this PR, and for your feedback.

I'd like to clarify the changes that I was aiming to make, and point out one that I think may have been looked over, which is completely understandable since the GitHub "Files changed" diff does not do a good job of highlighting the word-for-word changes that were proposed, and my commit messages did not clearly describe them.

Below are screenshots of the paragraph which I proposed changes to, exactly as it currently appears in the documentation. The first screenshot is from the current 1.x documentation, and the second screenshot is from the current 2.x documentation. I have added red underlining to the relevant words which I am proposing changes to, with the original goal of eliminating inconsistency between the two versions in mind.

In the first underline, I noticed that the 1.x documentation says "traditional relational and document databases" while the 2.x documentation "traditional relational databases, and document databases", So I added the word "databases" to the 1.x documentation after the word "relational" to make the two versions the same. Additionally, as you pointed out, I did omit the oxford comma, as it is typically used in a list of three or more items and not in a list of exactly two items, but I will defer to you on that.

In the second underline, I noticed that the 1.x documentation uses the possessive noun "organisation's' (with an apostrophe) to modify "department or development team", while the 2.x documentation includes the non-possessive noun "organisations" (no apostrophe), included as another item in the list with "department or development team". I changed the 1.x documentation to match the 2.x documentation. An alternative consideration I am having now is to replace this with "organisation, department, development team, etc.", since the namespace layer can be used for any number of ways to separate data, and is not limited to these three words. Please let me know what you think.

image

image