Docs and README copy editing (aerleon#319)

README.md

@@ -8,10 +8,10 @@ Generate firewall configs for multiple firewall platforms from a single platform
 
 Aerleon is a fork of [Capirca](https://github.com/google/capirca) with the following major additions:
 
-- YAML policy and network definitions files are supported. A [converter from Capirca's policy DSL to YAML](https://github.com/aerleon/pol2yaml) is available.
-- FQDN values are supported in network definitions.
-- Support for new firewall platforms can be added through plugins.
-- Typed Python APIs are provided for ACL generation and aclcheck queries.
+- YAML policy and network definition files and [pol2yaml, a converter from Capirca policy DSL to YAML](https://github.com/aerleon/pol2yaml).
+- Network definitions with FQDN data.
+- New firewall platforms can be added through plugins.
+- Typed Python APIs for ACL generation and aclcheck queries.
 - A [SLSA-compatible verifiable release process](https://aerleon.readthedocs.io/en/latest/install/#verifying-installation).
 - A detailed regression test suite.
 - Many bug fixes and performance enhancements.

docs/faq.md

@@ -5,3 +5,6 @@ Aerleon is a fork of the Capirca project, which was originally intended to be na
 
 ## Pronunciation?
 The origins of the name Capirca may not be familiar to everyone, and as a result, we have heard various pronunciations. These words are made up, so there is no one correct way to pronounce them. The maintainers of the project, however, pronounce Capirca as "Cap-irr-ca" and Aerleon as "Air-leon".
+
+## How To Convert Capirca Policy Files to YAML?
+The [pol2yaml](https://github.com/aerleon/pol2yaml) program, maintained by the Aerleon team, converts Capirca policy files to YAML policy files.

docs/getting_started.md

@@ -1,9 +1,11 @@
 # Getting Started with Aerleon
 
-The following sections will take you through a guided tour of Aerleon. We will cover general concepts such as Policy files, Network and Service definitions and putting them together to output firewall configurations.
+The following sections will take you through a guided tour of Aerleon. We will cover general concepts such as policy files, network and service definitions, and put them together to output firewall configurations.
 
 ## Setup
-> **_NOTE:_** This tutorial assumes you are working on a Linux operating system and have completed the [installation instructions](/en/latest/install/).
+!!! info
+
+ This tutorial assumes you are working on a Linux operating system and have completed the [installation instructions](/en/latest/install/).
 
 You will want to make a temporary directory with the following structure.
 ```bash
@@ -22,7 +24,7 @@ cd aerleon_test
 The rest of this walkthrough will assume you are within the `aerleon_test` directory.
 
 ## Definition Files
-Definition files allow you to define Networks and Services used in your policies. Generally it is much easier to read a name like `WEB_SERVERS` rather than a list of IP addresses. It is also beneficial to compose definitions together in certain places.
+Definition files allow you to define networks and services used in your policies. Generally it is much easier to read a name like `WEB_SERVERS` rather than a list of IP addresses. It is also beneficial to compose definitions together in certain places.
 
 ```yaml
 networks:

docs/index.md

@@ -8,9 +8,9 @@ Aerleon provides a per firewall platform configuration generator. It loads data
 
 The data primarily consists of:
 
-* Policy Files that represent the actual firewall rules.
-* Address Files that represent the addresses, in the form of named objects.
-* Service Files that represent the services, in the form of named objects.
+* Policy files that represent the actual firewall rules.
+* Address files that represent the addresses, in the form of named objects.
+* Service files that represent the services, in the form of named objects.
 
 ## Supported Configuration Formats
 

docs/install.md

@@ -5,7 +5,9 @@
  * If your system Python does not meet that requirement you can leverage [pyenv](https://github.com/pyenv/pyenv) to maintain one or more Python versions that can be set on a per directory basis.
 * [pip](https://pip.pypa.io/en/stable/getting-started/)
 
-**_NOTE:_** It is recommended to use a virtual environment such as the Python built-in [venv](https://docs.python.org/3/library/venv.html) module or the [virtualenv](https://virtualenv.pypa.io/en/latest/) package. 
+!!! tip
+
+ It is recommended to use a virtual environment such as the Python built-in [venv](https://docs.python.org/3/library/venv.html) module or the [virtualenv](https://virtualenv.pypa.io/en/latest/) package.
 
 Option 1: Install from PyPI.