Docs: Rewrite Bazel pages to clarify intended user, Part 4
PiperOrigin-RevId: 361612150
diff --git a/site/docs/query.html b/site/docs/query.html
index 48ae8a7..8755d13 100644
--- a/site/docs/query.html
+++ b/site/docs/query.html
@@ -121,11 +121,11 @@
"'a' + 'a'" # OK
</pre>
- <p>We chose this syntax so that quote marks aren't needed in most cases.
+ <p>This syntax doesn't need quote marks in most cases.
The (unusual) <code>".*test rule"</code> example needs quotes: it
starts with a period and contains a space.
Quoting <code>"cc_library"</code> is unnecessary but harmless.
- </p>
+ </p>
<li><b>Punctuation</b>, such as parens <code>()</code>, period
<code>.</code> and comma <code>,</code>, etc. Words containing
@@ -144,13 +144,13 @@
datatype.
</p>
<p>
- In some expressions, the partial order of the graph is
- not interesting; In this case, we call the values
- "sets". In cases where the partial order of elements
- is significant, we call values "graphs". Note
- that both terms refer to the same datatype, but merely emphasize
- different aspects of it.
+ Set and graph refer to the same datatype, but emphasize different
+ aspects of it, for example:
</p>
+<ul>
+ <li><b>Set:</b> The partial order of the targets is not interesting.</li>
+ <li><b>Graph:</b> The partial order of targets is significant.</li>
+</ul>
<h3>Cycles in the dependency graph</h3>
<p>
@@ -330,7 +330,7 @@
</pre>
<p>
- We will examine each of the productions of this grammar in order.
+ The following sections describe each of the productions of this grammar in order.
</p>
<h3 id="target-patterns">Target patterns</h3>
@@ -504,8 +504,8 @@
x intersect (y union z)</pre>
<p>
- (We strongly recommend that you use parentheses where there is
- any danger of ambiguity in reading a query expression.)
+ **Recommendation:** Use parentheses where there is
+ any danger of ambiguity in reading a query expression.
</p>
<h3 id="set">Read targets from an external source: set</h3>
diff --git a/site/docs/remote-caching-debug.md b/site/docs/remote-caching-debug.md
index 7b82d41..e1e8d36 100644
--- a/site/docs/remote-caching-debug.md
+++ b/site/docs/remote-caching-debug.md
@@ -12,11 +12,7 @@
locally and is set up to utilize remote caching, and that you want to ensure
that the remote cache is being effectively utilized.
-For tips on how to check your cache hit rate and how to compare the execution
-logs between two Bazel invocations, see [Debugging Remote Cache Hits for Remote
-Execution](/remote-execution-caching-debug.html). Everything presented in that
-guide also applies to remote caching with local execution. However, local
-execution presents some additional challenges which we will discuss here.
+For tips on how to check your cache hit rate and how to compare the execution logs between two Bazel invocations, see [Debugging Remote Cache Hits for Remote Execution](/remote-execution-caching-debug.html). Everything presented in that guide also applies to remote caching with local execution. However, local execution presents some additional challenges.
## Checking your cache hit rate
diff --git a/site/docs/remote-caching.md b/site/docs/remote-caching.md
index 826af30..eb1d9d1 100644
--- a/site/docs/remote-caching.md
+++ b/site/docs/remote-caching.md
@@ -309,9 +309,9 @@
**Input file modification during a build**
When an input file is modified during a build, Bazel might upload invalid
-results to the remote cache. We implemented a change detection that can be
-enabled via the `--experimental_guard_against_concurrent_changes` flag. There
-are no known issues and we expect to enable it by default in a future release.
+results to the remote cache. You can enable a change detection with
+the `--experimental_guard_against_concurrent_changes` flag. There
+are no known issues and it will be enabled by default in a future release.
See [issue #3360] for updates. Generally, avoid modifying source files during a
build.
diff --git a/site/docs/remote-execution-caching-debug.md b/site/docs/remote-execution-caching-debug.md
index 583fa04..567581f 100644
--- a/site/docs/remote-execution-caching-debug.md
+++ b/site/docs/remote-execution-caching-debug.md
@@ -37,7 +37,7 @@
### Ensure re-running the same build/test command produces cache hits
1. Run the build(s) and/or test(s) that you expect to populate the cache. The
- first time a new build is run on a particular stack, we expect no remote
+ first time a new build is run on a particular stack, you can expect no remote
cache hits. As part of remote execution, action results are stored in the
cache and a subsequent run should pick them up.
diff --git a/site/docs/remote-execution-rules.md b/site/docs/remote-execution-rules.md
index 2459596..a382f78 100644
--- a/site/docs/remote-execution-rules.md
+++ b/site/docs/remote-execution-rules.md
@@ -144,7 +144,7 @@
To help find potential non-hermetic behavior you can use [Workspace rules log](/workspace-log.md).
If an external dependency executes specific operations dependent on the host
-platform, we recommend splitting those operations between `WORKSPACE` and build
+platform, you should split those operations between `WORKSPACE` and build
rules as follows:
* **Platform inspection and dependency enumeration.** These operations are
