Improve wording of documentation (#990)

CONTRIBUTING.md

@@ -5,14 +5,14 @@ yourself.
 
 ## Set up your environment
 
-* See [DEVELOPMENT][DEVELOPMENT.md]
+- See [DEVELOPMENT][DEVELOPMENT.md]
 
 ## Resources
 
 ### Update nodes
 
-All node classes was auto-generated from image resource files. For example, the
-`diagram.aws.compute.EC2` class was auto-generated based on
+All node classes are auto-generated from image resource files. For example, the
+`diagram.aws.compute.EC2` class is auto-generated based on the
 `resources/aws/compute/ec2.png` image resource file.
 
 So, if you want to add new node resources or update existing node resources, you
@@ -30,13 +30,13 @@ ffmpeg -i my_big_image.jpg -vf scale=w=256:h=256:force_original_aspect_ratio=dec
 
 Then just run the `./autogen.sh` to generate the added or updated node classes. (cf. [DEVELOPMENT][DEVELOPMENT.md])
 
-> IMPORTANT NOTE: To run `autogen.sh`, you need [round][round], [black][black] and
-> [inkscape][inkscape] command lines that are used for cleaning the image
+> IMPORTANT NOTE: To run `autogen.sh`, you need the [round][round], [black][black] and
+> [inkscape][inkscape] command line tools that are used for cleaning the image
 > resource filenames and formatting the generated python code.
 >
-> macOS users can download the inkscape via Homebrew.
+> macOS users can download inkscape via Homebrew.
 >
-> Or you should use the docker image.
+> Or you can use the docker image.
 
 [DEVELOPMENT.md]: ./DEVELOPMENT.md
 [round]: https://github.com/mingrammer/round
@@ -54,11 +54,13 @@ or update the `ALIASES` map in [config.py](config.py).
 
 Then just run the `./autogen.sh` to generate the added or updated aliases. (cf. [DEVELOPMENT][DEVELOPMENT.md])
 
-> IMPORTANT NOTE: To run `autogen.sh`, you need [round][round] and
-> [inkscape][inkscape] command lines that are used for cleaning the image
+> IMPORTANT NOTE: To run `autogen.sh`, you need the [round][round] and
+> [inkscape][inkscape] command line tools that are used for cleaning the image
 > resource filenames.
 >
-> Or you should use the docker image.
+> macOS users can download inkscape via Homebrew.
+>
+> Or you can use the docker image.
 
 ## Run Tests
 

DEVELOPMENT.md

@@ -39,7 +39,7 @@ You should have docker installed in your system, if not click [here](https://doc
 
 ## Mac local development setup
 
-To be able to develop and run diagrams locally on you Mac device, you should have [Python](https://www.python.org/downloads/), [Go](https://golang.org/doc/install) and [brew](https://brew.sh/) installed on your system.
+To be able to develop and run diagrams locally on you Mac device, you should have [Python](https://www.python.org/downloads/), [Go](https://golang.org/doc/install), and [brew](https://brew.sh/) installed on your system.
 
 1. Go to diagrams root directory.
 

docs/getting-started/installation.md

@@ -3,11 +3,13 @@ id: installation
 title: Installation
 ---
 
-It requires **Python 3.6** or higher, check your Python version first.
+**diagrams** requires **Python 3.6** or higher, check your Python version first.
 
-It uses [Graphviz](https://www.graphviz.org/) to render the diagram, so you need to [install Graphviz](https://graphviz.gitlab.io/download/) to use **diagrams**. After installing graphviz (or already have it), install the **diagrams**.
+**diagrams** uses [Graphviz](https://www.graphviz.org/) to render the diagram, so you need to [install Graphviz](https://graphviz.gitlab.io/download/) to use it.
 
-> macOS users can download the Graphviz via `brew install graphviz` if you're using [Homebrew](https://brew.sh). Similarly, Windows users with [Chocolatey](https://chocolatey.org) installed can run `choco install graphviz`.
+> macOS users using [Homebrew](https://brew.sh) can install Graphviz via `brew install graphviz` . Similarly, Windows users with [Chocolatey](https://chocolatey.org) installed can run `choco install graphviz`.
+
+After installing Graphviz (or if you already have it), install **diagrams**:
 
 ```shell
 # using pip (pip3)
@@ -33,16 +35,18 @@ with Diagram("Web Service", show=False):
     ELB("lb") >> EC2("web") >> RDS("userdb")
 ```
 
-This code generates below diagram.
+To generate the diagram, run:
 
 ```shell
 $ python diagram.py
 ```
 
+This generates the diagram below:
+
 ![web service diagram](/img/web_service_diagram.png)
 
-It will be saved as `web_service.png` on your working directory.
+It will be saved as `web_service.png` in your working directory.
 
 ## Next
 
-See more [Examples](/docs/getting-started/examples) or see [Guides](/docs/guides/diagram) page for more details.
+See more [Examples](/docs/getting-started/examples) or see the [Guides](/docs/guides/diagram) page for more details.

docs/guides/cluster.md

@@ -3,13 +3,13 @@ id: cluster
 title: Clusters
 ---
 
-Cluster allows you group (or clustering) the nodes in an isolated group.
+`Cluster` allows you to group (or cluster) nodes in an isolated group.
 
 ## Basic
 
-Cluster represents a local cluster context.
+`Cluster` represents a local cluster context.
 
-You can create a cluster context with Cluster class. And you can also connect the nodes in a cluster to other nodes outside a cluster.
+You can create a cluster context using the `Cluster` class. You can also connect the nodes in a cluster to other nodes outside a cluster.
 
 ```python
 from diagrams import Cluster, Diagram
@@ -33,7 +33,7 @@ with Diagram("Simple Web Service with DB Cluster", show=False):
 
 ## Nested Clusters
 
-Nested clustering is also possible.
+Nested clustering is also possible:
 
 ```python
 from diagrams import Cluster, Diagram
@@ -68,4 +68,4 @@ with Diagram("Event Processing", show=False):
 
 ![event processing diagram](/img/event_processing_diagram.png)
 
-> There is no depth limit of nesting. Feel free to create nested clusters as deep as you want.
+> There is no depth limit to nesting. Feel free to create nested clusters as deep as you want.

docs/guides/diagram.md

@@ -3,13 +3,13 @@ id: diagram
 title: Diagrams
 ---
 
-Diagram is a primary object representing a diagram.
+`Diagram` is a primary object representing a diagram.
 
 ## Basic
 
-Diagram represents a global diagram context.
+`Diagram` represents a global diagram context.
 
-You can create a diagram context with Diagram class. The first parameter of Diagram constructor will be used for output filename.
+You can create a diagram context with the `Diagram` class. The first parameter of the `Diagram` constructor will be used to generate the output filename.
 
 ```python
 from diagrams import Diagram
@@ -19,17 +19,17 @@ with Diagram("Simple Diagram"):
     EC2("web")
 ```
 
-And if you run the above script with below command,
+If you run the above script with the command below,
 
 ```shell
 $ python diagram.py
 ```
 
-It will generate an image file with single `EC2` node drawn as `simple_diagram.png` on your working directory, and open that created image file immediately.
+it will generate an image file with single `EC2` node drawn as `simple_diagram.png` in your working directory and open that created image file immediately.
 
 ## Jupyter Notebooks
 
-Diagrams can be also rendered directly inside the notebook as like this:
+Diagrams can also be rendered directly inside Jupyter notebooks like this:
 
 ```python
 from diagrams import Diagram
@@ -42,9 +42,9 @@ diag
 
 ## Options
 
-You can specify the output file format with `outformat` parameter. Default is **png**.
+You can specify the output file format with the `outformat` parameter. The default is **png**.
 
-> (png, jpg, svg, pdf and dot) are allowed.
+> Allowed formats are: png, jpg, svg, pdf, and dot
 
 ```python
 from diagrams import Diagram
@@ -54,7 +54,7 @@ with Diagram("Simple Diagram", outformat="jpg"):
     EC2("web")
 ```
 
-The `outformat` parameter also support list to output all the defined output in one call.
+The `outformat` parameter also supports a list to output all the defined outputs in one call:
 
 ```python
 from diagrams import Diagram
@@ -64,7 +64,7 @@ with Diagram("Simple Diagram Multi Output", outformat=["jpg", "png", "dot"]):
     EC2("web")
 ```
 
-You can specify the output filename with `filename` parameter. The extension shouldn't be included, it's determined by the `outformat` parameter.
+You can specify the output filename with the `filename` parameter. The extension shouldn't be included, it's determined by the `outformat` parameter.
 
 ```python
 from diagrams import Diagram
@@ -74,7 +74,7 @@ with Diagram("Simple Diagram", filename="my_diagram"):
     EC2("web")
 ```
 
-You can also disable the automatic file opening by setting the `show` parameter as **false**. Default is **true**.
+You can also disable the automatic file opening by setting the `show` parameter to **false**. The default is **true**.
 
 ```python
 from diagrams import Diagram
@@ -84,7 +84,7 @@ with Diagram("Simple Diagram", show=False):
     EC2("web")
 ```
 
-It allows custom Graphviz dot attributes options.
+Diagrams also allow custom Graphviz dot attributes options.
 
 > `graph_attr`, `node_attr` and `edge_attr` are supported. Here is a [reference link](https://www.graphviz.org/doc/info/attrs.html).
 

docs/guides/edge.md

@@ -3,13 +3,13 @@ id: edge
 title: Edges
 ---
 
-Edge is representing an edge between Nodes.
+`Edge` represents an edge between nodes.
 
 ## Basic
 
-Edge is an object representing a connection between Nodes with some additional properties.
+`Edge` is an object representing a connection between nodes with some additional properties.
 
-An edge object contains three attributes: **label**, **color** and **style** which mirror corresponding graphviz edge attributes.
+An edge object contains three attributes: **label**, **color**, and **style**. They mirror the corresponding Graphviz edge attributes.
 
 ```python
 from diagrams import Cluster, Diagram, Edge

docs/guides/node.md

@@ -3,11 +3,11 @@ id: node
 title: Nodes
 ---
 
-Node is a second object representing a node or system component.
+`Node` is an object representing a node or system component.
 
 ## Basic
 
-Node is an abstract concept that represents a single system component object. 
+`Node` is an abstract concept that represents a single system component object.
 
 A node object consists of three parts: **provider**, **resource type** and **name**. You may already have seen each part in the previous example.
 
@@ -19,9 +19,9 @@ with Diagram("Simple Diagram"):
     EC2("web")
 ```
 
-In above example, the `EC2` is a node of `compute` resource type which provided by `aws` provider.
+In the example above, the `EC2` is a node of resource type `compute` which is provided by the `aws` provider.
 
-You can use other node objects in a similar manner like:
+You can use other node objects in a similar manner:
 
 ```python
 # aws resources
@@ -42,7 +42,7 @@ from diagrams.alibabacloud.storage import ObjectTableStore
 
 # gcp resources
 from diagrams.gcp.compute import AppEngine, GKE
-from diagrams.gcp.ml import AutoML 
+from diagrams.gcp.ml import AutoML
 ...
 
 # k8s resources
@@ -57,15 +57,17 @@ from diagrams.oci.network import Firewall
 from diagrams.oci.storage import FileStorage, StorageGateway
 ```
 
-You can find all available nodes list in [Here](https://diagrams.mingrammer.com/docs/nodes/aws).
+You can find lists of all available nodes for each provider in the sidebar on the left.
+
+For example, [here](https://diagrams.mingrammer.com/docs/nodes/aws) is the list of all available AWS nodes.
 
 ## Data Flow
 
-You can represent data flow by connecting the nodes with these operators: `>>`, `<<` and `-`.
+You can represent data flow by connecting the nodes with the operators `>>`, `<<`, and `-`.
 
-* **>>**: Connect nodes in left to right direction. 
-* **<<**: Connect nodes in right to left direction.
-* **-**: Connect nodes in no direction. Undirected.
+- **>>** connects nodes in left to right direction.
+- **<<** connects nodes in right to left direction.
+- **-** connects nodes in no direction. Undirected.
 
 ```python
 from diagrams import Diagram
@@ -80,15 +82,15 @@ with Diagram("Web Services", show=False):
     (ELB("lb") >> EC2("web")) - EC2("web") >> RDS("userdb")
 ```
 
-> Be careful when using the `-` and any shift operators together, which could cause unexpected results due to operator precedence. 
+> Be careful when using `-` and any shift operators together. It can cause unexpected results due to Python's operator precedence, so you might have to use parentheses.
 
 ![web services diagram](/img/web_services_diagram.png)
 
 > The order of rendered diagrams is the reverse of the declaration order.
 
-You can change the data flow direction with `direction` parameter. Default is **LR**.
+You can change the data flow direction with the `direction` parameter. The default is **LR**.
 
-> (TB, BT, LR and RL) are allowed.
+> Allowed values are: TB, BT, LR, and RL
 
 ```python
 from diagrams import Diagram
@@ -110,7 +112,7 @@ with Diagram("Workers", show=False, direction="TB"):
 
 ## Group Data Flow
 
-Above worker example has too many redundant flows. In this case, you can group nodes into a list so that all nodes are connected to other nodes at once.
+The above worker example has too many redundant flows. To avoid this, you can group nodes into a list so that all nodes are connected to other nodes at once:
 
 ```python
 from diagrams import Diagram

scripts/__init__.py

@@ -4,7 +4,7 @@ from pathlib import Path
 import config as cfg
 
 
-def base_dir() -> str:
+def base_dir() -> Path:
     return Path(os.path.abspath(os.path.dirname(__file__))).parent
 
 

templates/apidoc.tmpl

@@ -3,7 +3,7 @@ id: {{ pvd }}
 title: {{ pvd|up_or_title(pvd) }}
 ---
 
-Node classes list of {{ pvd }} provider.
+Node classes list of the {{ pvd }} provider.
 {% for typ, classes in typ_classes.items() %}
 ## {{ pvd }}.{{ typ }}
 {% for class in classes %}