Search: Rearrange README with Arch Board feedback (Azure#13116)

sdk/search/Azure.Search.Documents/README.md

@@ -201,26 +201,9 @@ SearchClient client = new SearchClient(endpoint, indexName, credential);
 There are two ways to interact with the data returned from a search query.
 Let's explore them with a search for a "luxury" hotel.
 
-#### Use `SearchDocument` like a dictionary
+#### Use C# types for Search Results
 
-`SearchDocument` is the default type returned from queries when you don't
-provide your own.  Here we perform the search, enumerate over the results, and
-extract data using `SearchDocument`'s dictionary indexer.
-
-```C# Snippet:Azure_Search_Tests_Samples_Readme_Dict
-SearchResults<SearchDocument> response = client.Search<SearchDocument>("luxury");
-foreach (SearchResult<SearchDocument> result in response.GetResults())
-{
-    SearchDocument doc = result.Document;
-    string id = (string)doc["hotelId"];
-    string name = (string)doc["hotelName"];
-    Console.WriteLine("{id}: {name}");
-}
-```
-
-#### Use C# types
-
-We can also decorate our own types with [attributes from `System.Text.Json`](https://docs.microsoft.com/dotnet/standard/serialization/system-text-json-how-to):
+We can decorate our own C# types with [attributes from `System.Text.Json`](https://docs.microsoft.com/dotnet/standard/serialization/system-text-json-how-to):
 
 ```C# Snippet:Azure_Search_Tests_Samples_Readme_StaticType
 public class Hotel
@@ -233,7 +216,7 @@ public class Hotel
 }
 ```
 
-And use them in place of `SearchDocument` when querying.
+Then we use them as the type parameter when querying to return strongly-typed search results:
 
 ```C# Snippet:Azure_Search_Tests_Samples_Readme_StaticQuery
 SearchResults<Hotel> response = client.Search<Hotel>("luxury");
@@ -247,6 +230,23 @@ foreach (SearchResult<Hotel> result in response.GetResults())
 If you're working with a search index and know the schema, creating C# types
 is recommended.
 
+#### Use `SearchDocument` like a dictionary for Search Results
+
+If you don't have your own type for search results, `SearchDocument` can be
+used instead.  Here we perform the search, enumerate over the results, and
+extract data using `SearchDocument`'s dictionary indexer.
+
+```C# Snippet:Azure_Search_Tests_Samples_Readme_Dict
+SearchResults<SearchDocument> response = client.Search<SearchDocument>("luxury");
+foreach (SearchResult<SearchDocument> result in response.GetResults())
+{
+    SearchDocument doc = result.Document;
+    string id = (string)doc["hotelId"];
+    string name = (string)doc["hotelName"];
+    Console.WriteLine("{id}: {name}");
+}
+```
+
 #### SearchOptions
 
 The `SearchOptions` provide powerful control over the behavior of our queries.
@@ -259,7 +259,7 @@ SearchOptions options = new SearchOptions
     // Filter to only ratings greater than or equal our preference
     Filter = SearchFilter.Create($"rating ge {stars}"),
     Size = 5, // Take only 5 results
-    OrderBy = new[] { "rating desc" } // Sort by rating from high to low
+    OrderBy = { "rating desc" } // Sort by rating from high to low
 };
 SearchResults<Hotel> response = client.Search<Hotel>("luxury", options);
 // ...
@@ -310,18 +310,6 @@ SearchIndex index = new SearchIndex("hotels")
 client.CreateIndex(index);
 ```
 
-### Retrieving a specific document from your index
-
-In addition to querying for documents using keywords and optional filters,
-you can retrieve a specific document from your index if you already know the
-key. You could get the key from a query, for example, and want to show more
-information about it or navigate your customer to that document.
-
-```C# Snippet:Azure_Search_Tests_Samples_Readme_GetDocument
-Hotel doc = client.GetDocument<Hotel>("1");
-Console.WriteLine($"{doc.Id}: {doc.Name}");
-```
-
 ### Adding documents to your index
 
 You can `Upload`, `Merge`, `MergeOrUpload`, and `Delete` multiple documents from
@@ -331,8 +319,8 @@ to be aware of.
 
 ```C# Snippet:Azure_Search_Tests_Samples_Readme_Index
 IndexDocumentsBatch<Hotel> batch = IndexDocumentsBatch.Create(
-IndexDocumentsAction.Upload(new Hotel { Id = "783", Name = "Upload Inn" }),
-IndexDocumentsAction.Merge(new Hotel { Id = "12", Name = "Renovated Ranch" }));
+    IndexDocumentsAction.Upload(new Hotel { Id = "783", Name = "Upload Inn" }),
+    IndexDocumentsAction.Merge(new Hotel { Id = "12", Name = "Renovated Ranch" }));
 
 IndexDocumentsOptions options = new IndexDocumentsOptions { ThrowOnAnyError = true };
 client.IndexDocuments(batch, options);
@@ -342,6 +330,18 @@ The request will succeed even if any of the individual actions fail and
 return an `IndexDocumentsResult` for inspection.  There's also a `ThrowOnAnyError`
 option if you only care about success or failure of the whole batch.
 
+### Retrieving a specific document from your index
+
+In addition to querying for documents using keywords and optional filters,
+you can retrieve a specific document from your index if you already know the
+key. You could get the key from a query, for example, and want to show more
+information about it or navigate your customer to that document.
+
+```C# Snippet:Azure_Search_Tests_Samples_Readme_GetDocument
+Hotel doc = client.GetDocument<Hotel>("1");
+Console.WriteLine($"{doc.Id}: {doc.Name}");
+```
+
 ### Async APIs
 
 All of the examples so far have been using synchronous APIs, but we provide full

sdk/search/Azure.Search.Documents/tests/Samples/Readme.cs

@@ -177,7 +177,7 @@ public async Task Options()
                 // Filter to only ratings greater than or equal our preference
                 Filter = SearchFilter.Create($"rating ge {stars}"),
                 Size = 5, // Take only 5 results
-                OrderBy = new[] { "rating desc" } // Sort by rating from high to low
+                OrderBy = { "rating desc" } // Sort by rating from high to low
             };
             SearchResults<Hotel> response = client.Search<Hotel>("luxury", options);
             // ...
@@ -257,8 +257,8 @@ public async Task Index()
             {
                 #region Snippet:Azure_Search_Tests_Samples_Readme_Index
                 IndexDocumentsBatch<Hotel> batch = IndexDocumentsBatch.Create(
-                IndexDocumentsAction.Upload(new Hotel { Id = "783", Name = "Upload Inn" }),
-                IndexDocumentsAction.Merge(new Hotel { Id = "12", Name = "Renovated Ranch" }));
+                    IndexDocumentsAction.Upload(new Hotel { Id = "783", Name = "Upload Inn" }),
+                    IndexDocumentsAction.Merge(new Hotel { Id = "12", Name = "Renovated Ranch" }));
 
                 IndexDocumentsOptions options = new IndexDocumentsOptions { ThrowOnAnyError = true };
                 client.IndexDocuments(batch, options);