Merge pull request swiftlang#33878 from varungandhi-apple/vg-doc-address-review-comments

Author: swift-ci

README.md

@@ -80,6 +80,8 @@ If you are interested in:
   up until the "Building the project" section. After that, follow the
   instructions in the [Swift Toolchains](#swift-toolchains) section below.
 
+We also have an [FAQ](/docs/HowToGuides/FAQ.md) that answers common questions.
+
 [Getting Started guide]: /docs/HowToGuides/GettingStarted.md
 
 ### Swift Toolchains
@@ -143,14 +145,14 @@ Try the suggestions in
 [Troubleshooting build issues](/docs/HowToGuides/GettingStarted.md#troubleshooting-build-issues).
 
 Make sure you are using the
-[correct release](/docs/HowToGuides/GettingStared.md#installing-dependencies)
+[correct release](/docs/HowToGuides/GettingStarted.md#installing-dependencies)
 of Xcode.
 
 If you have changed Xcode versions but still encounter errors that appear to
 be related to the Xcode version, try passing `--clean` to `build-script`.
 
 When a new version of Xcode is released, you can update your build without
-recompiling the entire project by passing the `--reconfigure` option.
+recompiling the entire project by passing `--reconfigure` to `build-script`.
 
 ## Learning More
 

docs/HowToGuides/FAQ.md

@@ -64,8 +64,14 @@ This very depends on what X is, but some broad guidelines are:
 1. Do a case-insensitive recursive string search.
    - Use a specialized tool like [ripgrep](https://github.com/BurntSushi/ripgrep)
      or [ag](https://github.com/ggreer/the_silver_searcher).
+   - Use `git grep --ignore-case "mypattern"`. `git grep` also supports helpful
+     flags which provide more context:
+     - `--show-function`: Tries to print the function name that a match was
+       found in.
+     - `--function-context`: Tries to print the entire surrounding function
+       containing the match.
    - Use 'Find in Workspace' in Xcode (<kbd>⌘</kbd>+<kbd>⇧</kbd>+<kbd>F</kbd>).
-   - Use `grep -i -r "mypattern" .`.
+   - Use `grep --ignore-case --recursive "mypattern" .`.
 2. Go through the [Documentation Index](/docs/README.md).
 
 ### How do I build the documentation as HTML?

docs/HowToGuides/FirstPullRequest.md

@@ -6,7 +6,7 @@ you are an experienced open source contributor who is excited about Swift, or
 maybe you are somewhere in-between. Regardless of your background, we are
 excited to have you contribute and improve the developer experience for Swift
 programmers all over the globe.
-:sparkles::child::student::woman_technologist::technologist::man_technologist::sparkles:
+:sparkles:🧒🏾🧑🏼‍🎓👩🏽‍💻🧑🏻‍💻👨🏿‍💻:sparkles:
 
 This document provides a high-level overview of different parts of the
 contribution process.

docs/HowToGuides/GettingStarted.md

@@ -19,7 +19,7 @@ toolchain as a one-off, there are a couple of differences:
   - [Ubuntu Linux](#ubuntu-linux)
 - [Building the project for the first time](#building-the-project-for-the-first-time)
   - [Spot check dependencies](#spot-check-dependencies)
-  - [Understanding the pieces](#understanding-the-pieces)
+  - [The roles of different tools](#the-roles-of-different-tools)
   - [The actual build](#the-actual-build)
   - [Troubleshooting build issues](#troubleshooting-build-issues)
 - [Editing code](#editing-code)
@@ -373,7 +373,7 @@ The codebase is your oyster!
 
 Now that you have made some changes, you will need to rebuild...
 
-### Incremental rebuilds with Ninja
+### Incremental builds with Ninja
 
 To rebuild the compiler:
 ```sh
@@ -503,7 +503,7 @@ utils/build-script --release-debuginfo --debug-swift # other flags...
 # debug Stdlib + optimized Swiftc + optimized Clang/LLVM
 utils/build-script --release-debuginfo --debug-swift-stdlib # other flags...
 
-# optimized Stdlib + debug Swiftc (expect typechecker) + optimized Clang/LLVM
+# optimized Stdlib + debug Swiftc (except typechecker) + optimized Clang/LLVM
 utils/build-script --release-debuginfo --debug-swift --force-optimized-typechecker
 
 # Last resort option, it is highly unlikely that you will need this