[doc] Correct link names and minor edits (RobotLocomotion#18125)

doc/_pages/apt.md

@@ -15,16 +15,17 @@ for additional compatibility details.
 To learn about other installation methods, refer to
 [Installation and Quickstart](/installation.html).
 
-If you experience any problems or questions with Drake, please
-[ask for help on Stack Overflow](/getting_help.html).
+If you experience any problems with or have questions about Drake, please
+[ask for help](/getting_help.html).
 
 Drake binary releases incorporate a pre-compiled version of
 [SNOPT](https://ccom.ucsd.edu/~optimizers/solvers/snopt/) as part of the
 [Mathematical Program toolbox](https://drake.mit.edu/doxygen_cxx/group__solvers.html).
 Thanks to Philip E. Gill and Elizabeth Wong for their kind support.
 
 Drake's apt packages do not support the Gurobi solver. To use
-Gurobi, you will need to [build Drake from source](/from_source.html).
+Gurobi, you will need to build Drake from source following the instructions
+in [Source Installation](/from_source.html).
 
 ## Stable Releases
 

doc/_pages/bazel.md

@@ -18,7 +18,7 @@ to install Bazel.
 
 * Start with a **git clone** of drake, per the [Getting Drake](/from_source.html#getting-drake)
   instructions.
-* Continue with the *"Mandatory platform specific instructions"* on the same
+* Continue with the *"Mandatory platform-specific instructions"* on the same
   page.
 
 # Developing Drake using Bazel

doc/_pages/code_review_checklist.md

@@ -122,14 +122,14 @@ Changes to third-party software (e.g., upgrading to a newer version) are the
 most common cause of CI divergence between Ubuntu and macOS.  For PRs with such
 changes, be sure to opt-in to a pre-merge macOS build.
 
-[Schedule one on-demand build](/jenkins.html#scheduling-an-on-demand-build) using an "everything"
+[Schedule an on-demand build](/jenkins.html#scheduling-an-on-demand-build) using an "everything"
 flavor, for example:
 
 * ``@drake-jenkins-bot mac-big-sur-clang-bazel-experimental-everything-release please``
 
 # Have you run linting tools?
 
-* See [Automated style checks](/code_style_tools.html).
+* See [Automated style checks](/code_style_tools.html#automated-style-checks).
 
 # Is your code deterministic?
 

doc/_pages/code_style_tools.md

@@ -3,8 +3,8 @@ title: Tools for Code Style Compliance
 ---
 
 This section provides a list of tools that some have found useful for ensuring
-their code abides by [Drake's coding style](/code_style_guide.html). The list
-is by no means comprehensive.
+their code abides by [Drake's Code Style Guide](/code_style_guide.html).
+The list is by no means comprehensive.
 If your favorite tools or methodologies are not listed, we would be delighted
 to learn about them. Please document your trick and submit a pull request!
 
@@ -33,14 +33,15 @@ User manuals for the style-checking tools are as follows:
   [http://pycodestyle.readthedocs.io/en/latest/intro.html](http://pycodestyle.readthedocs.io/en/latest/intro.html).
   * The syntax ``# noqa`` can be used to quiet the warning about an overly-long
     line.
-* Bazel: Uses both pycodestyle like Python, and also [buildifier](/bazel.html#updating-build-files).
+* Bazel: Uses both pycodestyle like Python, and also the buildifier tool as
+  described in [Updating BUILD files](/bazel.html#updating-build-files).
 
 
 # Manual style fixups
 
 ## C/C++: Clang-Format
 
-The [Mandatory platform specific instructions](/from_source.html#mandatory-platform-specific-instructions)
+The [Mandatory platform-specific instructions](/from_source.html#mandatory-platform-specific-instructions)
 install Drake's required version of ``clang-format``, depending on the platform
 (macOS or Ubuntu).
 

doc/_pages/developers.md

@@ -31,7 +31,7 @@ using an even more comprehensive set of unit tests.
 If problems are detected on this branch, the build cop will
 [revert the PRs that most likely caused the problem](buildcop.html).
 To increase the likelihood that your pull requests pass CI tests and are not
-reverted, you can run the unit tests locally. Instructions for how to do that
+reverted, you can run the unit tests locally; instructions for how to do that
 are provided [here](/unit_testing_instructions.html). Note, however, that there are
 many computationally-demanding tests and running the entire test suite can take
 several hours depending on your machine.
@@ -77,8 +77,8 @@ downgrade Bazel. If on Mac, there is no easy mechanism to downgrade with
 Homebrew; however, we generally try to stay on top of Bazel versions.
 
 If you have tried and are unable to configure your system by
-[following the instructions](/from_source.html) please do not hesitate
-to [ask for help](/getting_help.html).
+[following the instructions for source installation](/from_source.html)
+please do not hesitate to [ask for help](/getting_help.html).
 
 # Issue Tracking
 
@@ -110,7 +110,7 @@ green ``+###`` number as reported by github), and *must not* include more than
   * Data files do not count towards the line limit.
   * Machine-generated changes do not count towards the line limit.
   * Files in
-    [Special Directories](/directory_structure.html)
+    [Dev Directories](/directory_structure.html#dev-directories)
     do not count towards the line limit.
   * This rule may be overridden by agreement of at least two platform reviewers
     (listed below).
@@ -182,7 +182,7 @@ Choose the "Squash and merge option" unless otherwise instructed (see
 [Curated Commits](/reviewable.html#curated-commits)).
 
 **After Merge.** If your PR breaks continuous integration, the
-[buildcop](/buildcop.html) will contact you to work out a resolution.
+[build cop](/buildcop.html) will contact you to work out a resolution.
 
 
 ## Review Process Tooling

doc/_pages/directory_structure.md

@@ -7,9 +7,9 @@ components, (2) limit dependencies, and (3) prevent circular dependencies.
 
 # Dev Directories
 
-All code in Drake must adhere to the code standards described in
-[Developer Notes](/developers.html#developer-notes) and must be covered by tests, unless
-the code lives in a subdirectory named ``dev``.
+All code in Drake must adhere to the code standards described in the notes
+[For Developers](/developers.html#developer-notes) and must be covered by
+tests, unless the code lives in a subdirectory named ``dev``.
 
 To promote rapid development of research ideas, experimental code may be placed
 in a subdirectory named ``dev``.  We do not enforce code standards nor test

doc/_pages/docker.md

@@ -12,16 +12,17 @@ for additional compatibility details.
 To learn about other installation methods, refer to
 [Installation and Quickstart](/installation.html).
 
-If you experience any problems or questions with Drake, please
-[ask for help on Stack Overflow](/getting_help.html).
+If you experience any problems with or have questions about Drake, please
+[ask for help](/getting_help.html).
 
 Drake binary releases incorporate a pre-compiled version of
 [SNOPT](https://ccom.ucsd.edu/~optimizers/solvers/snopt/) as part of the
 [Mathematical Program toolbox](https://drake.mit.edu/doxygen_cxx/group__solvers.html).
 Thanks to Philip E. Gill and Elizabeth Wong for their kind support.
 
 Drake's docker images do not support the Gurobi solver. To use
-Gurobi, you will need to [build Drake from source](/from_source.html).
+Gurobi, you will need to build Drake from source following the instructions
+in [Source Installation](/from_source.html).
 
 ## Stable Releases
 

doc/_pages/doxygen_instructions.md

@@ -52,5 +52,5 @@ ascii-art block diagrams even prettier by replacing ``-``, ``|``, etc. with unic
 
 # Doxygen Website Generation
 
-To generate and view Drake's Doxygen website, see:
-[Documentation Instructions](/documentation_instructions.html).
+To generate and view Drake's Doxygen website, see the
+[Documentation Generation Instructions](/documentation_instructions.html).

doc/_pages/from_binary.md

@@ -12,16 +12,17 @@ for compatibility details.
 To learn about other installation methods, refer to
 [Installation and Quickstart](/installation.html).
 
-If you experience any problems or questions with Drake, please
-[ask for help on Stack Overflow](/getting_help.html).
+If you experience any problems with or have questions about Drake, please
+[ask for help](/getting_help.html).
 
 Drake binary releases incorporate a pre-compiled version of
 [SNOPT](https://ccom.ucsd.edu/~optimizers/solvers/snopt/) as part of the
 [Mathematical Program toolbox](https://drake.mit.edu/doxygen_cxx/group__solvers.html).
 Thanks to Philip E. Gill and Elizabeth Wong for their kind support.
 
 Drake's binary releases do not support the Gurobi solver. To use
-Gurobi, you will need to [build Drake from source](/from_source.html).
+Gurobi, you will need to build Drake from source following the instructions in
+[Source Installation](/from_source.html).
 
 ## Stable Releases
 
@@ -54,7 +55,7 @@ example.
 
 ### Use as a Python library
 
-In most cases, we suggest using our [pip releases](/pip.html), because that
+In most cases we suggest [installation via pip](/pip.html) because that
 will be more convenient than manually downloading.  However, if you are running
 on macOS arm64 or if you need both
 C++ and Python API support, then pip will not work.  This section shows

doc/_pages/from_source.md

@@ -63,7 +63,7 @@ git remote add upstream [email protected]:RobotLocomotion/drake.git
 git remote set-url --push upstream no_push
 ```
 
-# Mandatory platform specific instructions
+# Mandatory platform-specific instructions
 
 Before running the build, you must follow some one-time platform-specific
 setup steps:
@@ -77,8 +77,9 @@ All else being equal, we would recommend developers use Ubuntu Focal.
 
 # Build with Bazel
 
-For instructions, jump to [Using Bazel](/bazel.html#developing-drake-using-bazel), or check out the
-full details at:
+For instructions, jump to
+[Developing Drake using Bazel](/bazel.html#developing-drake-using-bazel),
+or check out the full details at:
 
 * [Bazel build system](/bazel.html)
 

doc/_pages/getting_help.md

@@ -7,7 +7,7 @@ title: Getting Help
 If you need help with Drake, please first review the documentation on this
 website for things such as [installation](/installation.html),
 the [C++ API](https://drake.mit.edu/doxygen_cxx/index.html), or
-[Python bindings](/python_bindings.html).
+[Using Drake from Python](/python_bindings.html).
 
 Please also briefly review
 [Drake's open and closed GitHub issues](https://github.com/RobotLocomotion/drake/issues?q=is%3Aissue)
@@ -55,7 +55,8 @@ When reporting an issue, please consider providing the following information
         * CMake version (``which cmake; cmake --version``)
         * CMake C++ compiler (``cmake -LA <path_to_source_dir> | grep 'CMAKE_.*_COMPILER'``)
     * Git revision (``git rev-parse --short HEAD``)
-    * [Building Drake](/from_source.html) vs. downstream project (like [drake_bazel_external](https://github.com/RobotLocomotion/drake-external-examples/tree/master/drake_bazel_external), [drake_cmake_external](https://github.com/RobotLocomotion/drake-external-examples/tree/master/drake_cmake_external))
+    * [Building Drake from source](/from_source.html) vs. downstream project
+    (like [drake_bazel_external](https://github.com/RobotLocomotion/drake-external-examples/tree/master/drake_bazel_external), [drake_cmake_external](https://github.com/RobotLocomotion/drake-external-examples/tree/master/drake_cmake_external))
 * If using binary release:
     * Download URL
     * Contents of ``drake/share/doc/drake/VERSION.TXT``

doc/_pages/installation.md

@@ -75,8 +75,8 @@ All other packages support both C++ and/or Python.
 | Using tar.gz download | [Stable](/from_binary.html#stable-releases) or [Nightly](/from_binary.html#nightly-releases) | [Stable](/from_binary.html#stable-releases) or [Nightly](/from_binary.html#nightly-releases) |
 | Using Docker Hub      | [Stable](/docker.html#stable-releases) or [Nightly](/docker.html#nightly-releases) | [Stable](/docker.html#stable-releases) or [Nightly](/docker.html#nightly-releases) |
 
-Alternatively, you can skip the pre-compiled binaries and
-[build Drake from source](/from_source.html).
+Alternatively, you can skip the pre-compiled binaries and build Drake
+following the instructions in [Source Installation](/from_source.html).
 
 Drake's binary releases do not support the Gurobi solver.
 To use Gurobi, you must build Drake from source.

doc/_pages/pip.md

@@ -13,16 +13,17 @@ version of `pip >= 20.3`.
 To learn about other installation methods, refer to
 [Installation and Quickstart](/installation.html).
 
-If you experience any problems or questions with Drake, please
-[ask for help on Stack Overflow](/getting_help.html).
+If you experience any problems with or have questions about Drake, please
+[ask for help](/getting_help.html).
 
 Drake binary releases incorporate a pre-compiled version of
 [SNOPT](https://ccom.ucsd.edu/~optimizers/solvers/snopt/) as part of the
 [Mathematical Program toolbox](https://drake.mit.edu/doxygen_cxx/group__solvers.html).
 Thanks to Philip E. Gill and Elizabeth Wong for their kind support.
 
 Drake's pip packages do not support the Gurobi solver. To use
-Gurobi, you will need to [build Drake from source](/from_source.html).
+Gurobi, you will need to build Drake from source following the instructions
+in [Source Installation](/from_source.html).
 
 ## Stable Releases
 

doc/_pages/reviewable.md

@@ -91,7 +91,7 @@ only fix code style problems, or only affect tests or documentation.
 Commits that contain breaking changes receive special attention in the release
 notes.  To aid the human editor in making that determination, you must add the
 tag ``release notes: breaking change`` to any PR that makes a breaking change
-to a [Stable API](/stable.html) without a deprecation period.
+to a [Stable API](/stable.html#stable-api) without a deprecation period.
 
 **release notes: newly deprecated**<br/>
 &nbsp;or<br/>

doc/_pages/sphinx_instructions.md

@@ -9,5 +9,5 @@ Sphinx is the framework for generating Drake's
 
 # Sphinx Website Generation
 
-To generate and view Drake's website, see:
-[Documentation Instructions](/documentation_instructions.html).
+To generate and view Drake's website, see the
+[Documentation Generation Instructions](/documentation_instructions.html).

doc/_pages/stable.md

@@ -18,13 +18,14 @@ In each release, new deprecations might be announced, and then those changes
 will be finalized 3+ minor versions later, without changing the major version
 number.
 
-Deprecation announcements appear in the [release notes](/release_notes.html)
-for each stable release. For C++ and Python API changes, we will also use the
-language mechanism to highlight the change when possible (`[[deprecated]]` for
-C++; `warnings.warn` for Python). However, those mechanisms will not always
-trigger in every case, and some deprecations will reach beyond what those tools
-can denote. Therefore, we still recommend that you monitor the release notes as
-the final arbiter of deprecation announcements.
+Deprecation announcements appear in the
+[release notes](/release_notes/release_notes.html) for each stable release.
+For C++ and Python API changes, we will also use the language mechanism to
+highlight the change when possible (`[[deprecated]]` for C++; `warnings.warn`
+for Python). However, those mechanisms will not always trigger in every case,
+and some deprecations will reach beyond what those tools can denote.
+Therefore, we still recommend that you monitor the release notes as the final
+arbiter of deprecation announcements.
 
 Due to our 3-month announcement window, we recommend upgrading your pinned
 version of Drake at least that frequently. If you wish to upgrade less
@@ -39,10 +40,10 @@ In general, we do not plan to backport fixes into prior stable releases.
 We define a large portion of Drake as our "Stable API" that you can rely
 on. For the Stable API, we aim to give at least 3 months of notice ahead of any
 disruption (via deprecation announcements in Drake's
-[release notes](/release_notes.html), and with compile-time or run-time
-warnings when feasible). Any element of Drake that is not explicitly documented
-to be part of the Stable API is deemed "unstable" and is subject to change or
-removal without prior notice.
+[release notes](/release_notes/release_notes.html), and with compile-time or
+run-time warnings when feasible). Any element of Drake that is not explicitly
+documented to be part of the Stable API is deemed "unstable" and is subject to
+change or removal without prior notice.
 
 The sub-headings below explain the Stable API for various facets of Drake.
 
@@ -204,12 +205,14 @@ We expect any C++ code linked against Drake within the same program to use the
 identical source revision and build flags of Drake as all other code within
 that program.
 
-Refer to [Installation](/installation.html) for the current details.
+Refer to [Installation and Quickstart](/installation.html) for the current
+details.
 
 # OS Support
 
 Drake intends to support the two most recent versions of Ubuntu LTS and macOS
 on an ongoing basis. That generally means that your OS must be no more than
 ~2-4 years old for Ubuntu, or ~2 years old for macOS.
 
-Refer to [Installation](/installation.html) for the current details.
+Refer to [Installation and Quickstart](/installation.html) for the current
+details.

doc/_pages/sublime_text.md

@@ -77,4 +77,4 @@ To view an 80 character-wide ruler:
 ```
 
 Always displaying a ruler is useful to conform to
-[Drake’s coding style](/code_style_guide.html).
+[Drake's Code Style Guide](/code_style_guide.html).