Repository: bazelbuild/bazel
Issue: Bazel docs - do lightweight content formatting fixes
Labels: type: documentation (cleanup)
P1

For example, make https://docs.bazel.build/versions/2.1.0/bazel-vision.html less wall-o'-texty.

The broader goal is to make docs inviting, accessible, not intimidating. The less encyclopedic (i.e. dense) each page is the better.

https://github.com/bazelbuild/bazel/issues/10791 should also help by using bigger fonts and enforcing better maximum column widths.

Issue comments:

Pull request review comments:
For this and all other level2+ headers, should we use **Capitalize All Words** formatting or **Only first word**?

This and the the very next header disagree. And we have inconsistent use all throughout the docset. I'm happy to do a docset-wide refactoring if we can agree on the answer.

I suspect the answer is **Only first word**. But I have no authority to point to.
will md-format rewrite this?
Fixed.

Patch that resolved the issue:
diff --git a/site/docs/bazel-vision.md b/site/docs/bazel-vision.md
index d0aad8a996f545..7e2680f2ac9ae5 100644
--- a/site/docs/bazel-vision.md
+++ b/site/docs/bazel-vision.md
@@ -5,9 +5,9 @@ title: Bazel Vision
 
 # Bazel Vision
 
-<font size='+1'>Any software developer can efficiently build, test, and package
+<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
-extend.</font>
+extend.</font></p>
 
 *   **Engineers can take build fundamentals for granted.** Software developers
     focus on the creative process of authoring code because the mechanical
@@ -15,6 +15,7 @@ extend.</font>
     support new languages or unique organizational needs, users focus on the
     aspects of extensibility that are unique to their use case, without having
     to reinvent the basic plumbing.
+
 *   **Engineers can easily contribute to any project.** A developer who wants to
     start working on a new project can simply clone the project and run the
     build. There's no need for local configuration - it just works. With
@@ -22,23 +23,30 @@ extend.</font>
     fully test their changes against all platforms the project targets.
     Engineers can quickly configure the build for a new project or incrementally
     migrate an existing build.
+
 *   **Projects can scale to any size codebase, any size team.** Fast,
     incremental testing allows teams to fully validate every change before it is
     committed. This remains true even as repos grow, projects span multiple
     repos, and multiple languages are introduced. Infrastructure does not force
     developers to trade test coverage for build speed.
 
-**We believe Bazel has the potential to fulfill this vision.** Bazel was built
-from the ground up to enable builds that are reproducible (a given set of inputs
-will always produce the same outputs) and portable (a build can be run on any
-machine without affecting the output). These characteristics support safe
-incrementality (rebuilding only changed inputs doesn't introduce the risk of
-corruption) and distributability (build actions are isolated and can be
-offloaded). By minimizing the work needed to do a correct build and
-parallelizing that work across multiple cores and remote systems, Bazel can make
-any build fast. Bazel's abstraction layer—instructions specific to languages,
-platforms, and toolchains implemented in a simple extensibility language —
-allows it to be easily applied to any context.
+---
+
+**We believe Bazel has the potential to fulfill this vision.**
+
+Bazel was built from the ground up to enable builds that are reproducible (a
+given set of inputs will always produce the same outputs) and portable (a build
+can be run on any machine without affecting the output).
+
+These characteristics support safe incrementality (rebuilding only changed
+inputs doesn't introduce the risk of corruption) and distributability (build
+actions are isolated and can be offloaded). By minimizing the work needed to do
+a correct build and parallelizing that work across multiple cores and remote
+systems, Bazel can make any build fast.
+
+Bazel's abstraction layer — instructions specific to languages, platforms, and
+toolchains implemented in a simple extensibility language — allows it to be
+easily applied to any context.
 
 ## Bazel Core Competencies
 
@@ -60,9 +68,11 @@ allows it to be easily applied to any context.
 ## Serving language communities
 
 Software engineering evolves in the context of language communities — typically,
-self-organizing groups of people who use common tools and practices. To be of
-use to members of a language community, high-quality Bazel rules must be
+self-organizing groups of people who use common tools and practices.
+
+To be of use to members of a language community, high-quality Bazel rules must be
 available that integrate with the workflows and conventions of that community.
+
 Bazel is committed to be extensible and open, and to support good rulesets for
 any language.
 
@@ -84,6 +94,7 @@ any language.
     material for new users, comprehensive docs for expert users.
 
 Each of these items is essential and only together do they deliver on Bazel's
-competencies for their particular ecosystem. They are also, by and large,
-sufficient - once all are fulfilled, Bazel fully delivers its value to members
-of that language community.
+competencies for their particular ecosystem.
+
+They are also, by and large, sufficient - once all are fulfilled, Bazel fully
+delivers its value to members of that language community.


Test patch: