search

MicrosoftDocs / azure-docs

Open source documentation of Microsoft Azure
https://docs.microsoft.com/azure
Creative Commons Attribution 4.0 International
10.27k stars 21.45k forks source link

Grammar: is "auto-failover groups" singular or plural? #39974

Closed yobyot closed 4 years ago

yobyot commented 5 years ago

The first two sentences on this page read, in part:

"Auto-failover groups is a SQL Database feature that allows you to manage replication and failover of a group of databases on a SQL Database server or all databases in a managed instance to another region. It is a declarative abstraction..."

I think the feature as described in these sentences is plural, not singular. So, "Auto-failover groups are..." and "They are a declarative abstraction..."

In general, Azure documentation suffers from strained syntax and poor grammar. This is just one example. The lousy English across the service makes it much harder to understand and use Azure.

Document Details

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

NavtejSaini-MSFT commented 5 years ago

@yobyot Thanks for the feedback. We are looking into this.

NavtejSaini-MSFT commented 5 years ago

@yobyot This has been assigned to doc author for review. @anosov1960 Please look into this and advise if we need to create a PR for this. @stevestein For awareness that this should be taken as a general feedback on the docs and we help each other in fixing the same

anosov1960 commented 4 years ago

reassign: @MashaMSFT

I am not sure if it is incorrect but if so pls fix the grammar.

CarlRabeler commented 4 years ago

correct syntax should be: "The auto failover groups feature in SQL Database allows you to ...."

yobyot commented 4 years ago

That edit would be both grammatically correct and syntactically tortured. The purpose in opening this issue so long ago was to suggest that doc writers make the product easier to grasp by writing correctly and clearly.

CarlRabeler commented 4 years ago

why is that syntax syntactically tortured? auto failover groups is a single feature that uses a plural word in the name of the feature - a complexity that we, as writers, do not control.

MashaMSFT commented 4 years ago

I agree that the name of the feature being plural causes some challenges that writers cannot control, but the term "feature" is singular, and should be treated as such.

I have processed the following change going live later this week:

The auto-failover groups feature allows you to manage the replication and failover of a group of databases on a server or all databases in a managed instance to another region. It is a declarative abstraction on top

Thanks so much for your feedback and caring about the quality of our docs @yobyot!

I hope that helps and you have a wonderful rest of your day! Please feel free to comment should you need anything further. Masha from the SQL Docs team

please-close

MashaMSFT commented 4 years ago

By the way, @yobyot , I just wanted to let you know in case you were interested - you have the ability to modify docs yourself.

To do so, please do the following:

  1. Navigate to the page of interest
  2. Select the "Edit" button at the top right of the page
  3. Select the "Pencil" icon on the right
  4. Modify the text within the text box in markdown format - more info: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
  5. Name your file change and provide a description, if necessary
  6. Select "Propose file change"
  7. Select "Create pull request" on the 'Comparing changes' page
  8. Select "Create pull request" on the 'Open a pull request' page

The content team reviews the changes and if they're appropriate, we approve them so that you are marked as a contributor to the documentation.

Passing that along, just as an FYI if this is something you feel passionately about :)

Thanks again and have a great day! Masha from the SQL Docs team