Reword, fix spelling mistakes, and reformat development docs

docs/development/abstractions.md

@@ -2,11 +2,11 @@
 title: Abstractions
 ---
 
-This project and the apparmor profile official project provide a large selection of abstractions to be included in profiles. They should always be used as they target wide compatibility across hardware and distribution wile only allowing the bare minimum access.
+This project and the official apparmor-profiles project provide a large selection of abstractions to be included in profiles. They should always be used as they target wide compatibility across hardware and distributions while only allowing the bare minimum access.
 
 !!! example
 
-    For instance, to allow download directory access, instead of writing:
+    For instance, to allow download directory access instead of read and write permissions:
     ```sh
     owner @{HOME}/@{XDG_DOWNLOAD_DIR}/{,**} rw,
     ```
@@ -21,13 +21,13 @@ All of these abstractions can be extended by a system admin by adding rules in a
 
 ## Application helper
 
-Abstraction that aim at including a complete set of rule for a given program. The calling profile only need to add rules dependant of its use case/program.
+Abstraction that aims at including a complete set of rules for a given program. The calling profile only needs to add rules dependant of its use case/program.
 
 It is mostly useful for program often used in sub profile or for forks based on the same upstream.
 
 ### **`app/chromium`**
 
-Full set of rules for all chromium based browsers. It works as a *function* and requires some variables to be provided as *arguments* and set in the header of the calling profile:
+A full set of rules for all chromium based browsers. It works as a *function* and requires some variables to be provided as *arguments* and to be set in the header of the calling profile:
 
 !!! note ""
 
@@ -49,7 +49,7 @@ instead.
 
 ### **`app/sudo`**
 
-Minimal set of rules for profile including internal `sudo`. Interactive sudo need more rules. It is intended to be used in profile or sub profile that need to elevate their privileges using `sudo` or `su` for a very specific action:
+A minimal set of rules for profiles including internal `sudo`. Interactive sudo needs more rules. It is intended to be used in profiles or sub-profiles that need to elevate their privileges using `sudo` or `su` for a very specific action:
 ```sh
   @{bin}/sudo rCx  -> root,
 
@@ -63,7 +63,7 @@ Minimal set of rules for profile including internal `sudo`. Interactive sudo nee
 
 ### **`app/systemctl`**
 
-Alternative solution for [child-systemctl](structure.md#children-profiles), when the child profile provide too much/not enough access. This abstraction should be used by a sub profile as follows:
+An alternative solution for [child-systemctl](structure.md#children-profiles), when the child profile provides too much/not enough access. This abstraction should be used by a sub profile as follows:
 ```sh
   @{bin}/systemctl  rCx ->  systemctl,
 
@@ -82,7 +82,7 @@ On the contrary of [`abstractions/app/`](#application-helper), abstractions in t
 
 ### **`common/app`**
 
-Common rules for unknown userland UI applications sandboxed using `bwrap`.
+Common rules for unknown userland UI applications that are sandboxed using `bwrap`.
 
 !!! warning
 
@@ -93,11 +93,11 @@ Common rules for unknown userland UI applications sandboxed using `bwrap`.
 
 ### **`common/apt`**
 
-Minimal access to apt sources, preferences and configuration.
+Minimal access to apt sources, preferences, and configuration.
 
 ### **`common/bwrap`**
 
-Minimal set of rules for sandboxed program using `bwrap`. A profile using this abstraction still needs to set:
+Minimal set of rules for sandboxed programs using `bwrap`. A profile using this abstraction still needs to set:
 
 - The flag: `attach_disconnected`
 - Bwrap execution: `@{bin}/bwrap rix,`
@@ -105,12 +105,12 @@ Minimal set of rules for sandboxed program using `bwrap`. A profile using this a
 
 ### **`common/chromium`**
 
-Minimal set of rules for chromium based application. Handle access for internal sandbox.
+A minimal set of rules for chromium based application. Handle access for internal sandbox.
 
 
 ### **`common/electron`**
 
-Minimal set of rules for all electron based UI application. It works as a *function* and requires some variables to be provided as *arguments* and set in the header of the calling profile:
+A minimal set of rules for all electron based UI applications. It works as a *function* and requires some variables to be provided as *arguments* and set in the header of the calling profile:
 
 !!! note ""
 
@@ -139,7 +139,7 @@ Most programs do not need access to audio devices, `audio-client` only includes
 
 ### **`audio-server`**
 
-Provide access to audio devices. It should only be used by audio servers that need direct access to them. 
+Provides access to audio devices. It should only be used by audio servers that need direct access to them. 
 
 
 ## Dbus
@@ -156,16 +156,16 @@ This abstraction gives read access on all defined user directories. It should on
 
 ### **`user-download-strict`**
 
-Provide write access to all user download directories
+Provides write access to all user download directories
 
 
 ### **`deny-sensitive-home`**
 
-Deny access to some sensitive directories under `/home/`. It is intended to be used by the few profiles that legitimately require full unrestricted access over all user directories (file browser and search engines). It allows to us to block access to really sensitive data to such profiles.
+Denies access to some sensitive directories under `/home/`. It is intended to be used by the few profiles that legitimately require full unrestricted access over all user directories (file managers and search engines). It allows to us to block access to really sensitive data to such profiles.
 
 !!! danger
 
-    **Do not use this abstraction for other profile without explicit authorisation from the project maintainer**
+    **Do not use this abstraction for other profiles without explicit authorisation from the project maintainer**
 
     Per the **[Rule :material-numeric-1-circle:](index.md#rule-mandatory-access-control)** of this project:
 
@@ -205,7 +205,7 @@ Common rules for interactive shell using zsh.
 
 ### **`nameservice-strict`**
 
-Many programs wish to perform nameservice like operations, such as looking up users by name or Id, groups by name or Id, hosts by name or IP, etc.
+Many programs wish to perform nameservice like operations, such as looking up users by name or ID, groups by name or ID, hosts by name or IP, etc.
 
 Use this abstraction instead of upstream `abstractions/nameservice` as upstream abstraction also provide full network access which is not needed for a lot of programs.
 
@@ -218,36 +218,36 @@ Instead of allowing the run of all software under `@{bin}` or `@{lib}` the purpo
 
 ### **`devices-usb`**
 
-Provide access to USB devices
+Provides access to USB devices
 
 ### **`disks-write`**
 
-Provide read write access to disks devices
+Provides read write access to disks devices
 
 ### **`disks-read`**
 
-Provide read only access to disks devices
+Provides read-only access to disks devices
 
 
 ## Desktop Environment
 
 ### **`desktop`**
 
-Unified minimal abstraction for all UI application regardless of the desktop environment. When supported in apparmor, condition will be used in this abstraction to filter resources specific for supported DE.
+Unified minimal abstraction for all UI applications regardless of the desktop environment. When supported in apparmor, the condition will be used in this abstraction to filter resources specific for supported DE.
 
-It is safe to use it in GUI application. As well as minimal desktop resource files, it includes access to configuration for: `fonts`, `gtk` & `qt`, `wayland` & `xorg`.
+It is safe to use this in GUI applications as well as minimal desktop resource files, it includes access to configuration for: `fonts`, `gtk` & `qt`, `wayland` & `xorg`.
 
 ### **`gnome-strict`**
 
-Same than `abstractions/desktop` but limited to gnome.
+Same as `abstractions/desktop` but limited to gnome.
 
 ### **`kde-strict`**
 
-Same than `abstractions/desktop` but limited to KDE.
+Same as `abstractions/desktop` but limited to KDE.
 
 ## Graphics
 
-Use either [`graphics`](#graphics) or [`graphics-full`](#graphics-full). The other abstractions are hardware/software dependant and should not usually be used directly.
+Use either [`graphics`](#graphics) or [`graphics-full`](#graphics-full). The other abstractions are hardware/software dependent and should not usually be used directly.
 
 ### **`graphics`**
 
@@ -261,7 +261,7 @@ Identical to [`graphics`](#graphics) with more direct access to nvidia GPU devic
 
 ### **`dri`**
 
-Linux's graphics stack which allows unprivileged user-space programs to issue commands to graphics hardware without conflicting with other programs. Mostly used by Intel (integrated or not) and AMD GPU.
+Linux's graphics stack which allows unprivileged user-space programs to issue commands to graphics hardware without conflicting with other programs. Mostly used by Intel (integrated or not) and AMD GPUs.
 
 Modernized equivalent of both `dri-common` and `dri-enumerate`
 

docs/development/dbus.md

@@ -2,19 +2,19 @@
 title: Dbus
 ---
 
-All dbus rules are labelled under the name of the given profiles that provide dbus data. It is one of the value added by this project, as we have profile for *everything*, we can restrict the bus further by limitint connection to a given peer label (the profile name). In case of a renaming of a profile, all dbus rules related it this profile need to be updated accordingly.
+All dbus rules are labelled under the name of the given profiles that provide dbus data. It is one of the value added by this project, as we have profiles for *everything*, we can restrict the bus further by limiting connection to a given peer label (the profile name). In the case of renaming a profile, all dbus rules related in this profile need to be updated accordingly.
 
 ## Profiles
 
 Regardless of the Dbus implementation used (`dbus-daemon` or `dbus-broker`), all dbus daemons are handled under the same set of profiles: [`dbus-system`](https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/groups/bus/dbus-system), [`dbus-session`](https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/groups/bus/dbus-session), and [`dbus-accessibility`](https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/groups/bus/dbus-accessibility). This structure largely improves the confinement of each profile.
 
-To ensure system and session bus are handled by a different profile, a [systemd drop-in](https://github.com/roddhjav/apparmor.d/blob/main/systemd/default/system/dbus.service) configuration file is used to set the specific dbus profile a dbus service must use.
+To ensure the system and session bus are handled by a different profile, a [systemd drop-in](https://github.com/roddhjav/apparmor.d/blob/main/systemd/default/system/dbus.service) configuration file is used to set the specific dbus profile that a dbus service must use.
 
 ## Abstractions
 
 ### Base
 
-Default **system**, **session** and **accessibility** bus access are provided with the abstraction:
+Default **system**, **session**, and **accessibility** bus access are provided with the following abstractions:
 
 - `abstractions/bus-system`
 - `abstractions/bus-session`
@@ -22,13 +22,13 @@ Default **system**, **session** and **accessibility** bus access are provided wi
 
 ### Interfaces
 
-Access to common dbus interface is done using the abstractions under **[`abstractions/bus/`](https://github.com/roddhjav/apparmor.d/tree/main/apparmor.d/abstractions/bus)**. They are kept minimal on purpose. The goal is not to give full talk access an interface but to provide a *read-only* like view of it. It may be required to have a look at the dbus interface documentation to check what method can be safely allowed.
+Access to common dbus interfaces is done using the abstractions under **[`abstractions/bus/`](https://github.com/roddhjav/apparmor.d/tree/main/apparmor.d/abstractions/bus)**. They are kept minimal on purpose. The goal is not to give full talk access an interface but to provide a *read-only* like view of it. It may be required to have a look at the dbus interface documentation to check what method can be safely allowed.
 
 For more access, simply use the [`aa:dbus talk`](#dbus-directive) directive.
 
 ## Dbus Directive
 
-We use a special [directive](directives.md) to generate more advanced dbus access. The directive format is on purpose very similar to the apparmor dbus rule.
+We use a special [directive](directives.md) to generate more advanced dbus access. The directive format is on purpose very similar to the AppArmor dbus rule.
 
 **Format**
 
@@ -40,8 +40,8 @@ We use a special [directive](directives.md) to generate more advanced dbus acces
 
 :    Access type. Can be `own` or `talk`:
 
-     - `own` means the profile own the dbus interface. It is allowed to send and receive from anyone on this interface.
+     - `own` means the profile owns the dbus interface. It is allowed to send and receive from anyone on this interface.
-     - `talk` means the profile can talk on a given interface to the profile owning it (that must be given under the `label` option).
+     - `talk` means the profile can talk on a given interface to the profile that owns it (a label must be given under the `label` option).
 
 **`<bus>`**
 
@@ -64,7 +64,7 @@ We use a special [directive](directives.md) to generate more advanced dbus acces
 :    Can optionally be given when it is different to the dbus name.
 
 
-Note: `<access>`, `<bus>` and `<name>` are mandatory and will break the build if ignored.
+Note: `<access>`, `<bus>`, and `<name>` are mandatory and will break the build if ignored.
 
 
 **Example**
@@ -78,7 +78,7 @@ Allow owning a dbus interface:
     #aa:dbus own bus=system name=org.freedesktop.NetworkManager
     ```
 
-Allow talking to a dbus interface on a given profile
+Allow talking to a dbus interface on a given profile:
 
 !!! note ""
 
@@ -142,4 +142,4 @@ Allow talking to a dbus interface on a given profile
           peer=(name="{:1.@{int},org.freedesktop.login1{,.*}}", label=systemd-logind),
      dbus send bus=system path=/org/freedesktop/Accounts{,/**}
           interface=org.freedesktop.Accounts{,.*}
-     ```
+     ```

docs/development/directives.md

@@ -2,7 +2,7 @@
 title: Directives
 ---
 
-`apparmor.d` supports build directives, they are processed at build time of the project, when running `make`. They are valid apparmor comment, therefore, `apparmor_parser` can be used on a profile even if the directives have not been processed. They should not end with a comma. Multiline directive is not supported.
+`apparmor.d` supports build directives, they are processed at build time of the project. They are valid AppArmor comments, therefore, `apparmor_parser` can be used on a profile even if the directives have not been processed. They should not end with a comma. Multiline directive is not supported.
 
 The directives follow the format:
 ```sh
@@ -25,7 +25,7 @@ See the [dbus page](dbus.md#dbus-directive).
     
 ## Only, Exclude
 
-The `only` and `exclude` directives can be used to filter individual rule or rule paragraph depending on the target distribution of distribution family.
+The `only` and `exclude` directives can be used to filter individual rule or rule paragraphs depending on the target distribution or distribution family.
 
 **Format**
 
@@ -58,12 +58,12 @@ The `only` and `exclude` directives can be used to filter individual rule or rul
 `#aa:only pacman`
 
 :   
-    Remove the line/paragraph when the project is not compiled on the Archlinux family.
+    Remove the line/paragraph when the project is not compiled on the Arch Linux family.
 
 
 ## Exec
 
-The `exec` directive is useful to allow executing transition to a profile without having to manage the possible long list of profile attachment (it varies depending on the distribution). The directive parse and resolve the attachment variable (`@{exec_path}`) of the target profile and include it in the current profile.
+The `exec` directive is useful to allow executing transitions to a profile without having to manage the possible long list of profile attachments (it varies depending on the distribution). The directives parse and resolve the attachment variable (`@{exec_path}`) of the target profile and includes it in the current profile.
 
 **Format**
 
@@ -73,7 +73,7 @@ The `exec` directive is useful to allow executing transition to a profile withou
 
 **`profiles...`**
 
-:   List of profile **file** that can be executed from the current profile.
+:   List of profile **files** that can be executed from the current profile.
 
 **`[transition]`**
 
@@ -113,7 +113,7 @@ The `exec` directive is useful to allow executing transition to a profile withou
 
 **`profiles...`**
 
-:   List a profile **file** to stack at the end of the current profile.
+:   List a profile **files** to stack at the end of the current profile.
 
 
 **Example**

docs/development/guidelines.md

@@ -4,11 +4,11 @@ title: Guidelines
 
 ## Common structure
 
-AppArmor profiles can be written without any specific guidelines. However, when you work with over 1400 profiles, you need a common structure among all the profiles. 
+AppArmor profiles can be written without any specific guidelines. However, when you work with over 1500 profiles, you need a common structure among all the profiles. 
 
-The logic behind it is that if a rule is present in a profile, it should only be in one place, making profile review easier. 
+The logic behind it is that if a rule is present in a profile, it should only be in one place, making it easier to review profiles. 
 
-For example, if a program needs to run executables binary. The rules allowing it can only be in a specific rule block (just after the `@{exec_path} mr,` rule). It is therefore easy to ensure some profile features such as:
+For example, if a program needs to run executable binaries then the rules allowing it can only be in a specific rule block (just after the `@{exec_path} mr,` rule). It is therefore easy to ensure some profile features such as:
 
 * A profile has access to a given resource 
 * A profile enforces a strict [write xor execute] (W^X) policy. 
@@ -50,7 +50,7 @@ The rules in the profile should be sorted in the rule ***block*** as follows:
 
 This rule order is taken from AppArmor with minor changes as we tend to:
 
-- Divide the file block in multiple subcategories
+- Divide the file block into multiple subcategories
 - Put the block with the longer rules (`files`, `dbus`) after the other blocks
 
 ### The file block
@@ -93,7 +93,7 @@ If there is no predictable label it can be omitted.
 
 #### :material-numeric-1-circle: Variables
 
-:   Always use the apparmor [variables](../variables.md).
+:   Always use the apparmor.d [variables](../variables.md).
     Example:
 
     - `/usr/lib` or `/usr/bin` become `@{bin}` or `@{lib}`
@@ -101,15 +101,15 @@ If there is no predictable label it can be omitted.
 
 #### :material-numeric-2-circle: Sort
 
-:   In a rule block, the rules must be alphabetically sorted.
+:   In a rule block, all rules must be alphabetically sorted.
 
-#### :material-numeric-3-circle: Sub profile
+#### :material-numeric-3-circle: Sub-profiles
 
-:   Sub profile should come at the end of a profile.
+:   Sub-profiles should come at the end of a profile.
 
 #### :material-numeric-4-circle: Similar purpose
 
-:   When some rules share similar purpose, they may be sorted together. Eg:
+:   When some rules share similar purposes, they may be sorted together. E.g.:
     ```
     /etc/machine-id r,
     /var/lib/dbus/machine-id r,

docs/development/index.md

@@ -2,15 +2,15 @@
 title: Development
 ---
 
-You want to contribute to `apparmor.d`, **thanks a lot for this.** Feedbacks, contributors, pull requests are all very welcome. You will find in this page all the useful information needed to contribute.
+If you're looking to contribute to `apparmor.d` you can get started by going to the project [GitHub repository](https://github.com/roddhjav/apparmor.d/)! All contributions are welcome no matter how small. In this page you will find all the useful information needed to contribute to the apparmor.d project.
 
-??? info "How to contribute"
+??? info "How to contribute pull requests"
 
     1. If you don't have git on your machine, [install it](https://help.github.com/articles/set-up-git/).
-    2. Fork this repo by clicking on the fork button on the top of the [project Github][project] page.
+    2. Fork this repo by clicking on the fork button on the top of the [project GitHub][project] page.
-    3. Clone the repository and go to the directory:
+    3. Clone the forked repository and go to the directory:
     ```sh
-    git clone https://github.com/this-is-you/apparmor.d.git
+    git clone https://github.com/your-github-username/apparmor.d.git
     cd apparmor.d
     ```
     4. Create a branch:
@@ -20,7 +20,7 @@ You want to contribute to `apparmor.d`, **thanks a lot for this.** Feedbacks, co
     5. Make the changes and commit:
     ```
     git add <files changed>
-    git commit -m "A message for sum up my contribution"
+    git commit -m "A message to sum up my contribution"
     ```
     6. Push changes to GitHub:
     ```
@@ -34,13 +34,13 @@ You want to contribute to `apparmor.d`, **thanks a lot for this.** Feedbacks, co
 
 #### Rule :material-numeric-1-circle: - Mandatory Access Control
 
-:   As these are mandatory access control policies only what is explicitly required
+:   As these are mandatory access control policies **only** what is explicitly required
     should be authorized. Meaning, you should **not** allow everything (or a large area)
     and deny some sub areas.
 
 #### Rule :material-numeric-2-circle: - Do not break a program
 
-:   A profile **should not break a normal usage of the confined software**. It can
+:   A profile **should not break a normal usage of the confined software**. this can
     be complex as simply running the program for your own use case is not always
     exhaustive of the program features and required permissions.
 
@@ -50,7 +50,7 @@ You want to contribute to `apparmor.d`, **thanks a lot for this.** Feedbacks, co
 
 #### Rule :material-numeric-4-circle: - Distribution and devices agnostic
 
-:   A profile should be compatible with all distributions, software and devices
+:   A profile should be compatible with all distributions, software, and devices
     in the Linux world. You cannot deny access to resources you do not use on
     your devices or for your use case.
 

docs/development/install.md

@@ -6,14 +6,14 @@ title: Installation
 
 !!! warning
 
-    Do **not** install this project *"manually"* (with `make`, `sudo make install`). The distribution specific packages are intended to be used in development as they include additional rule to ensure compatibility with upstream. 
+    Do **not** install this project *"manually"* (with `make`, `sudo make install`). The distribution specific packages are intended to be used in development as they include additional rule to ensure compatibility with upstream. You have been warned!
 
     See `debian/`, `PKGBUILD` and `dists/apparmor.d.spec`.
 
 
 **:material-docker: Docker**
 
-From any distribution, if you have docker installed, you can simply build the package with:
+For any system with docker installed you can simply build the package with:
 ```sh
 make package dist=<distribution>
 ```
@@ -52,4 +52,4 @@ gnome-shell attach_disconnected,mediate_deleted,complain
 
 ## Ignore profiles
 
-It can be handy to not install a profile for a given distribution. Profile or directory to ignore are tracked under the [`dists/ignore`](https://github.com/roddhjav/apparmor.d/tree/main/dists/ignore) directory. Files in this directory should respect the following format: `<profile or path>`. One ignore by line. It can be a profile name or a directory to ignore (relative to the project root).
+It can be handy to not install a profile for a given distribution. Profiles and directories to ignore are tracked under the [`dists/ignore`](https://github.com/roddhjav/apparmor.d/tree/main/dists/ignore) directory. Files in this directory should respect the following format: `<profile or path>`. One ignore by line. It can be a profile name or a directory to ignore (relative to the project root).

docs/development/integration.md

@@ -4,13 +4,13 @@ title: Integration Tests
 
 !!! danger "Work in Progress"
 
-The purpose of integration testing in apparmor.d is to ensure the profiles are not going to break a program when used in the Linux distribution and desktop environment we support.
+The purpose of integration testing in apparmor.d is to ensure the profiles are not going to break programs found in Linux distributions and Desktop Environment that we support.
 
 **Workflow**
 
-1. Build some tests VM
+1. Create a testing VM
 2. Start the VM, do some dev
-3. Run the integration test against a given test VM
+3. Run the integration tests against the testing VM
 4. Ensure no new logs have been raised
 
 
@@ -47,7 +47,7 @@ To build a VM image for development purpose, run the following from the `tests`
 | Arch Linux | Gnome | `make archlinux flavor=gnome` | `arch-gnome` |
 | Arch Linux | KDE | `make archlinux flavor=kde` | `arch-kde` |
 | Debian | Server | `make debian flavor=server` | `debian-server` |
-| OpenSUSE | KDE | `make opensuse falvor=kde` | `opensuse-kde` |
+| OpenSUSE | KDE | `make opensuse flavor=kde` | `opensuse-kde` |
 | Ubuntu | Server | `make ubuntu flavor=server` | `ubuntu-server` |
 | Ubuntu | Desktop | `make ubuntu falvor=desktop` | `ubuntu-desktop` |
 
@@ -59,7 +59,7 @@ The development workflow is done through vagrant:
 * Shutdown a VM: `vagrant halt <name>`
 * Reboot a VM: `vagrant reload <name>`
 
-The available VM `name` are defined in the `tests/boxes.yml` file
+The available VM `name` is defined in the `tests/boxes.yml` file
 
 
 ### Develop
@@ -70,11 +70,11 @@ The admin user is: `user`, its password is: `user`. It has passwordless sudo acc
 
 **Directories**
 
-All the images come pre-configured with the lastest version of `apparmor.d` installed and running in the VM. The apparmor.d is mounted as `/home/user/Projects/apparmor.d`
+All the images come pre-configured with the latest version of `apparmor.d` installed and running in the VM. apparmor.d is mounted as `/home/user/Projects/apparmor.d`
 
 **Usage**
 
-On all images, `aa-update` can be used to rebuild and install latest version of the profiles. `p`, `pf`, and `pu` are two preconfigured aliases of `ps` that show the security status of processes. `htop` is also configured to show this status.
+On all images, `aa-update` can be used to rebuild and install the latest version of the profiles. `p`, `pf`, and `pu` are two preconfigured aliases of `ps` that show the security status of processes. `htop` is also configured to show this status.
 
 
 ## Tests
@@ -106,7 +106,7 @@ Initialise the tests with:
 ./aa-test --bootstrap
 ```
 
-List the tests scenario to be run
+List the tests scenarios to be run
 ```sh
 ./aa-test --list
 ```

docs/development/structure.md

@@ -19,15 +19,14 @@ It gets even worse. Let's say, we write a profile for `cat`. Such a profile woul
 However, as `/etc` can contain sensitive files, we now want to explicitly prevent access to these sensitive files. Problems:
 
 1. How do we know the exhaustive list of *sensitive files* in `/etc`?
-2. How do we ensure access to these sensitive files are not required?
+2. How do we ensure access to these sensitive files is not required?
 3. This breaks the principle of mandatory access control.
-   See the [first rule of this project](index.md#project-rules) that is to only allow
+   See the [first rule of this project](index.md#project-rules) which is to only allow
    what is required. Here we allow everything and blacklist some paths.
 
-It creates even more issues when we want to use this profile in other profiles. Let's take the example of `diff`. Using this rule: `@{bin}/diff rPx,` will restrict access to the very generic and not very confined `diff` profile. Whereas most of the time, we want to restrict `diff` to some specific file in our profile:
+It creates even more issues when we want to use this profile in other profiles. Let's take the example of `diff`. Using this rule: `@{bin}/diff rPx,` this will restrict access to the very generic and not very confined `diff` profile. Whereas most of the time, we want to restrict `diff` to some specific file in our profile:
 
-* In `dpkg`, an internal child profile (`rCx -> diff`), allows `diff` to only
+* In `dpkg`, an internal child profile (`rCx -> diff`), allows `diff` to only access etc config files:
-  access etc config files:
 
 !!! note ""
 
@@ -54,10 +53,7 @@ It creates even more issues when we want to use this profile in other profiles.
     }
     ```
 
-* In `pass`, as it is a dependency of pass. Here `diff` inherits pass' profile 
+* As it is a dependency of pass, `diff` inherits the `pass' profile and has the same access as the pass profile, so it will be allowed to diff password files because more than a generic `diff`, it is a `diff` "version" for the pass password manager:
-  and has the same access than the pass profile, so it will be allowed to diff
-  password files because more than a generic `diff` it is a `diff` for the pass
-  password manager:
 
 !!! note ""
 
@@ -69,14 +65,12 @@ It creates even more issues when we want to use this profile in other profiles.
 
 **What if I still want to protect these programs?**
 
-You do not protect these programs. *Protect the usage you have of these programs*.
+You do not protect these programs. *Protect the usage you have of these programs*. In practice, it means that you should put your terminal in a sandbox managed environment with a sandboxing tool such as Toolbox.
-In practice, it means that you should put your development's terminal in a
-sandbox managed with [Toolbox].
 
 !!! example "To sum up"
 
-    1. Do not a create profile for programs such as: `rm`, `ls`, `diff`, `cd`, `cat`
+    1. Do not create a profile for programs such as: `rm`, `ls`, `diff`, `cd`, `cat`
-    2. Do not a create profile for the shell: `bash`, `sh`, `dash`, `zsh`
+    2. Do not create a profile for the shell: `bash`, `sh`, `dash`, `zsh`
     3. Use [Toolbox].
 
 [Toolbox]: https://containertoolbx.org/
@@ -85,7 +79,7 @@ sandbox managed with [Toolbox].
 
 ## Abstractions
 
-This project and the apparmor profile official project provide a large selection of abstractions to be included in profiles. They should be used.
+This project and the apparmor-profiles official project provide a large selection of abstractions to be included in profiles. They should be used.
 
 For instance, to allow download directory access, instead of writing:
 ```sh
@@ -104,26 +98,17 @@ Usually, a child profile is in the [`children`][children] group. They have the f
 
 !!! quote
 
-    Note: This profile does not specify an attachment path because it is
+    Note: This profile does not specify an attachment path because it is intended to be used only via `"Px -> child-open"` exec transitions from other profiles. 
-    intended to be used only via `"Px -> child-open"` exec transitions
-    from other profiles. 
 
 [children]: https://github.com/roddhjav/apparmor.d/blob/main/apparmor.d/groups/children
 
 Here is an overview of the current children profile:
 
-1. **`child-open`**: To open resources. Instead of allowing the run of all
+1. **`child-open`**: To open resources. Instead of allowing the ability to run all software in `@{bin}/`, the purpose of this profile is to list all GUI programs that can open resources. Ultimately, only sandbox manager programs such as `bwrap`, `snap`, `flatpak`, `firejail` should be present here. Until this day, this profile will be a controlled mess.
-   software in `@{bin}/`, the purpose of this profile is to list all GUI
-   programs that can open resources. Ultimately, only sandbox manager programs
-   such as `bwrap`, `snap`, `flatpak`, `firejail` should be present here. Until
-   this day, this profile will be a controlled mess.
 
-2. **`child-pager`**: Simple access to pager such as `pager`, `less` and `more`.
+2. **`child-pager`**: Simple access to pagers such as `pager`, `less` and `more`. This profile assumes the pager is reading its data from stdin, not from a file on disk.
-   This profile supposes the pager is reading its data from stdin, not from a
-   file on disk.
 
-3. **`child-systemctl`**: Common `systemctl` action. Do not use it too much as most
+3. **`child-systemctl`**: Common `systemctl` action. Do not use it too much as most of the time you will need more privilege than what this profile is giving you.
-   of the time you will need more privilege than what this profile is giving you.
 
 
 ## Browsers
@@ -162,7 +147,7 @@ Special care must be given as sometimes udev numbers are allocated dynamically b
 
 ## No New Privileges
 
-[**No New Privileges**](https://www.kernel.org/doc/html/latest/userspace-api/no_new_privs.html) is a flag preventing a newly-started program to get more privileges that its parent. So it is a **good thing** for security. And it is commonly used in systemd unit files (when possible). This flag also prevents transition to other profile because it could be less restrictive than the parent profile (no `Px` or `Ux` allowed).
+[**No New Privileges**](https://www.kernel.org/doc/html/latest/userspace-api/no_new_privs.html) is a flag preventing a newly started program to get more privileges than its parent process. This is a **good thing** for security. And it is commonly used in systemd unit files (when possible). This flag also prevents transitions to other profiles because it could be less restrictive than the parent profile (no `Px` or `Ux` allowed).
 
 The possible solutions are:
 

docs/development/tests.md

@@ -2,7 +2,7 @@
 title: Tests suite
 ---
 
-A full test suite to ensure compatibility across distributions and software is still a work in progress. Here is an overview of the current CI jobs:
+A full test suite to ensure compatibility across supported distributions and that software is still considered a work in progress. Here is an overview of the current CI jobs:
 
 **On Gitlab CI**
 
@@ -12,6 +12,4 @@ A full test suite to ensure compatibility across distributions and software is s
 
 **On Github Action**
 
-- Integration test on the ubuntu-latest VM: run a simple list of tasks with
+- Integration test on the ubuntu-latest VM: run a simple list of tasks with all the rules enabled and ensure no new issue has been raised. Github Action is used as it offers direct access to a VM with AppArmor included.
-  all the rules enabled and ensure no new issue has been raised. Github Action
-  is used as it offers direct access to a VM with AppArmor included.