Docs: Update headers in Bazel overview pages
PiperOrigin-RevId: 343606251
diff --git a/site/docs/bazel-and-java.md b/site/docs/bazel-and-java.md
index d6160b8..eda5292 100644
--- a/site/docs/bazel-and-java.md
+++ b/site/docs/bazel-and-java.md
@@ -57,7 +57,7 @@
* Tests should be in a matching directory under `src/test` and depend on this
library.
-## Java and new rules
+## Creating new rules for advanced Java builds
**Note**: Creating new rules is for advanced build and test scenarios.
You do not need it when getting started with Bazel.
diff --git a/site/docs/bazel-and-javascript.md b/site/docs/bazel-and-javascript.md
index 4baeca3..4f9e6a7 100644
--- a/site/docs/bazel-and-javascript.md
+++ b/site/docs/bazel-and-javascript.md
@@ -9,8 +9,6 @@
It links to build rules and other information specific to building JavaScript
with Bazel.
-## Working with Bazel
-
The following resources will help you work with Bazel on JavaScript projects:
* [Building JavaScript/TypeScript with Bazel](build-javascript.html)
diff --git a/site/docs/bazel-container.md b/site/docs/bazel-container.md
index 77f6723..e4fe885 100644
--- a/site/docs/bazel-container.md
+++ b/site/docs/bazel-container.md
@@ -1,9 +1,9 @@
---
layout: documentation
-title: Bazel Container
+title: Bazel container
---
-# Getting started with Bazel Docker Container
+# Getting Started with Bazel Docker Container
In this guide, we will explore the contents of the Bazel container, build the
[abseil-cpp](https://github.com/abseil/abseil-cpp) project using Bazel inside
diff --git a/site/docs/bazel-overview.md b/site/docs/bazel-overview.md
index ce4e156..57360fc 100644
--- a/site/docs/bazel-overview.md
+++ b/site/docs/bazel-overview.md
@@ -1,9 +1,9 @@
---
layout: documentation
-title: Bazel overview
+title: Bazel Overview
---
-# Bazel overview
+# Bazel Overview
Bazel is an open-source build and test tool similar to Make, Maven, and Gradle.
It uses a human-readable, high-level build language. Bazel supports projects in
@@ -11,7 +11,7 @@
large codebases across multiple repositories, and large numbers of users.
-## Why should I use Bazel?
+## Benefits
Bazel offers the following advantages:
@@ -41,7 +41,7 @@
framework.
-## How do I use Bazel?
+## Using Bazel
To build or test a project with Bazel, you typically do the following:
@@ -75,7 +75,7 @@
to trace dependencies in your code.
-## How does Bazel work?
+## Bazel build process
When running a build or a test, Bazel does the following:
@@ -96,7 +96,7 @@
and maximizing [reproducibility](guide.html#correctness).
-### What is the action graph?
+### Action graph
The action graph represents the build artifacts, the relationships between them,
and the build actions that Bazel will perform. Thanks to this graph, Bazel can
@@ -106,7 +106,7 @@
easily [trace dependencies](query-how-to.html) in your code.
-## How do I get started?
+## Getting started tutorials
To get started with Bazel, see [Getting Started](getting-started.html) or jump
directly to the Bazel tutorials:
diff --git a/site/docs/bazel-vision.md b/site/docs/bazel-vision.md
index 7a3d4f7..e658831 100644
--- a/site/docs/bazel-vision.md
+++ b/site/docs/bazel-vision.md
@@ -3,7 +3,7 @@
title: Bazel vision
---
-# Bazel vision
+# Bazel Vision
<p><font size='+1'>Any software developer can efficiently build, test, and package
any project, of any size or complexity, with tooling that's easy to adopt and
@@ -74,7 +74,7 @@
Bazel is committed to be extensible and open, and to support good rulesets for
any language.
-### So what is a good ruleset?
+### Requirements of a good ruleset
1. The rules need to support efficient **building and testing** for the
language, including code coverage.
diff --git a/site/docs/best-practices.md b/site/docs/best-practices.md
index d3d233e..0f6198c 100644
--- a/site/docs/best-practices.md
+++ b/site/docs/best-practices.md
@@ -3,7 +3,7 @@
title: Best practices
---
-# Best practices for Bazel
+# Best Practices
This document assumes that you are familiar with Bazel and provides advice on structuring your
projects to take full advantage of Bazel's features.
@@ -32,9 +32,9 @@
targets to be filtered at a more fine-grained level than the "manual" tag and allows someone
inspecting the BUILD file to understand what a target's restrictions are.
-## Third party dependencies
+## Third-party dependencies
-You may declare third party dependencies:
+You may declare third-party dependencies:
* Either declare them as remote repositories in the WORKSPACE file.
* Or put them in a directory called `third_party/` under your workspace directory.
@@ -58,7 +58,7 @@
could end up with a library that tries to depend on two different versions. If you created a
misleading alias to point both targets to one guava library, then the BUILD files are misleading.
-## `.bazelrc`
+## Using the `.bazelrc` file
For project-specific options, use the configuration file your
`<workspace>/.bazelrc` (see [bazelrc format](guide.html#bazelrc)).
diff --git a/site/docs/build-event-protocol.md b/site/docs/build-event-protocol.md
index 5f0ec45..3262d59 100644
--- a/site/docs/build-event-protocol.md
+++ b/site/docs/build-event-protocol.md
@@ -1,9 +1,9 @@
---
layout: documentation
-title: Build event protocol
+title: Build Event Protocol
---
-# Build event protocol
+# Build Event Protocol
The [Build Event
Protocol](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream.proto)
@@ -18,8 +18,6 @@
Protocol is intended to be consumed programmatically and makes parsing Bazel’s
command line output a thing of the past.
-## Overview
-
The Build Event Protocol represents information about a build as events. A
build event is a protocol buffer message consisting of a build event identifier,
a set of child event identifiers, and a payload.
@@ -44,7 +42,7 @@
payload might not be the expected type, but could be an `Aborted` message e.g.
if the build aborted prematurely.
-### Build event graph
+### Build Event graph
All build events form a directed acyclic graph through their parent and child
relationship. Every build event except for the initial build event has one or
@@ -53,7 +51,7 @@
all announced events will have been posted. In case of a Bazel crash or a failed
network transport, some announced build events may never be posted.
-## The Build Event Protocol by example
+## Build Event Protocol example
The full specification of the Build Event Protocol can be found in its protocol
buffer definition and describing it here is beyond the scope of this document.
@@ -147,9 +145,9 @@
}
```
-## Consuming the Build Event Protocol
+## Consuming Build Event Protocol
-### Consume in a binary format
+### Consume in binary format
To consume the Build Event Protocol in a binary format:
@@ -164,17 +162,17 @@
2. Then, write a program that extracts the relevant information from the
serialized protocol buffer message.
-### Consume in text formats
+### Consume in text or JSON formats
-The following Bazel command line flags will output the Build Event Protocol in a
-human-readable formats:
+The following Bazel command line flags will output the Build Event Protocol in
+human-readable formats, such as text and JSON:
```
--build_event_text_file
--build_event_json_file
```
-## The Build Event Service
+## Build Event Service
The [Build Event
Service](https://github.com/googleapis/googleapis/blob/master/google/devtools/build/v1/publish_build_event.proto)
diff --git a/site/docs/build-javascript.md b/site/docs/build-javascript.md
index f5dc71d..db83dfb 100644
--- a/site/docs/build-javascript.md
+++ b/site/docs/build-javascript.md
@@ -31,13 +31,13 @@
To set up your environment for building JavaScript outputs with Bazel, do the
following:
-### Step 1: Installing Bazel
+### Installing Bazel
You can either [Install Bazel](install.html) following the same steps that you
would for backend development, or you can install NodeJS with npm and run
`npm install -g @bazel/bazel`.
-### Step 2: Installing iBazel
+### Installing iBazel
iBazel, or iterative Bazel, is a "watchdog" version of Bazel that automatically
runs whenever your source files change. Use it to auto-run your tests and
@@ -61,7 +61,7 @@
To use `ibazel`, simply replace `bazel` with `ibazel` in your Bazel commands.
-### Step 3: Configuring the `bazel.rc` file
+### Configuring the `bazel.rc` file
Any Bazel build flag or option that can be placed on the command line can also
be set in the project's [`bazel.rc` file](guide.html#bazelrc)
