Merge "Freshness for top-viewed API Council docs" into main

1 files changed, 13 insertions, 16 deletions

diff --git a/api-guidelines/index.md b/api-guidelines/index.md
index fa341cf..d24a9b8 100644
--- a/api-guidelines/index.md
+++ b/api-guidelines/index.md
@@ -1,15 +1,14 @@
 # Android API Guidelines
 
-This document is intended to be a general guide for developers to use to adhere
-to the general principles that the API Council enforces in API reviews.
+This document is intended to be a guide for developers to understand the general
+principles that the API Council enforces in API reviews.
 
-In addition to understanding and following these guidelines when writing APIs,
-developers should run the API Lint tool, which encodes many of these rules in
-checks that it runs against APIs.
+In addition to following these guidelines when writing APIs, developers should
+run the [API Lint](#apilint) tool, which encodes many of these rules in checks
+that it runs against APIs.
 
 Think of this as the guide to the rules that are obeyed by that Lint tool, plus
-guidelines and general advice on rules that cannot be easily codified into that
-tool.
+general advice on rules that cannot be easily codified into that tool.
 
 [TOC]
 
@@ -18,12 +17,9 @@ tool.
 [API Lint](https://source.corp.google.com/h/googleplex-android/platform/superproject/main/+/main:tools/metalava/src/main/java/com/android/tools/metalava/ApiLint.kt)
 is integrated into the Metalava static analysis tool and runs as part of the
 platform build. You can run it manually from an
-[AOSP checkout](https://source.android.com/setup/build/downloading) with:
-
-```bash
-# Run lint on all APIs
-$ m checkapi
-```
+[AOSP platform checkout](https://source.android.com/setup/build/downloading)
+using `m checkapi`. To run the tool from a Jetpack checkout, run the `./gradlew
+checkApi` task.
 
 ## API rules {#rules}
 
@@ -42,7 +38,7 @@ This category pertains to the core aspects of an Android API.
 
 ### All APIs must be implemented <a name="basics-implemented"></a>
 
-Irrespective of an API's audience (Public, @SystemApi, etc), all API surfaces
+Irrespective of an API's audience (public, `@SystemApi`, etc.), all API surfaces
 must be implemented when merged or exposed as API. Merging API stubs with
 implementation to come at a later date would be a violation of this guideline.
 
@@ -84,9 +80,10 @@ All platform APIs must be associated with a
 [flaggedapi]: https://source.corp.google.com/h/googleplex-android/platform/superproject/main/+/main:frameworks/libs/modules-utils/java/android/annotation/FlaggedApi.java?q=symbol%3A%5Cbandroid.annotation.FlaggedApi%5Cb%20case%3Ayes
 
 Note: For FAQ on API flagging, please visit
-[FAQ on API Flagging](/api-guidelines/faq.md) page
+[FAQ on API Flagging](/api-guidelines/faq.md)
+page.
 
-### All auto-generated APIs must be compliant with the guidelines <a name="basics-auto-generated-code"></a>
+### All generated APIs must be compliant with the guidelines <a name="basics-auto-generated-code"></a>
 
 APIs generated by tools must follow the API guidelines just the same as
 hand-written code.