fix: makeEnglishFrom ...

Author: blaggacao

ARCHITECTURE.md

@@ -11,21 +11,18 @@ This design document shall be stable and amendments go through a proper process
 ## Overview
 
 Standard is a collection of functionality and best practices (_"framework"_) to bootstrap and sustain the automatable sections of the Software Delivery Lifecycle (SDLC) _efficiently_ with the power of Nix and Flakes.
-In particular, Standard is a _Horizontal Integration Framework_ which integrates _vertical_ tooling.
+In particular, Standard is a _Horizontal\* Integration Framework_ which integrates _vertical\*_ tooling.
 
-> Glossary:
+> <sub>We occasionally adapt concepts from non-technical contexts. This is one instance.</sub>
 >
 > _Vertical Tooling_ does one thing and does it well in a narrow scope (i.e "vertical").
 >
 > _Horizontal Tooling_ stitches vertical tooling together to a polished whole.
->
-> <sub>
-> Where does this terminology come from?
-> We occasionally borrow concepts from organizational science.
-> </sub>
 
-In that context, subject to integration are the end-to-end automatable sections of the SDLC process for which we offer well-integrated tools and best practices.
-_Efficient_ SDLCs are characterized by two things.
+What is being integrated are the end-to-end automatable sections of the SDLC.
+For these we curate a collection of functionality, tools and best practices.
+
+An SDLCs _efficiency_ on the is characterized by two things.
 
 Firstly, by adequate _lead time_ which is the amount of time it takes to set up an initial version of the software delivery pipeline.
 It needs to be _adequate_ rather than _just fast_, as it takes place in the context of a team.
@@ -94,14 +91,14 @@ And we focus on:
 
 Where is Standard located in the big picture?
 
-This graphic locates Standard across the SDLC & ALM.
+This graphic locates Standard across the SDLC & Application Lifecycle Management (ALM).
 
 But not only that.
 It also explains how automation in itself is implemented as _code_, just as the application itself.
 Therefore, we make a distinction between:
 
-- first order application code on the first level (L1); and
-- higher order supporting code on higher levels as exemplified by L2 and L3.
+- first order application code (L1); and
+- above that, higher order supporting code as exemplified by L2 and L3.
 
 > Glossary:
 >
@@ -125,7 +122,7 @@ They are abstract definitions of artifact classes.
 Those abstract classes implement _shared functionality_.
 
 A few examples of artifact classes in our scope are: packages, containers, scripts and manifests, among others.
-Examples of shared functionality are _push_ on containers and on packages _build_.
+Examples of shared functionality are _push_ on containers and _build_ on packages.
 
 _**Cells**_, in turn, organize your code into related units of functionality.
 Hence, Cells are a code _orgnization principle_.
@@ -141,11 +138,11 @@ On the right side of the graphic, we sketch an idea how these components are put
 
 ### Paisano (Code Organization)
 
-We already learnt about Paisano's two main abstractions: Cells & Block Types.
+We already learned about Paisano's two main abstractions: Cells & Block Types.
 
 Cells enable and encourage the user to cleanly organize their code into related units of functionality.
 The concrete semantics of code layout are completely at her choosing.
-For example, she could separate application tiers like frontend and backend into their own Cell, each.
+For example, she could separate application tiers like frontend and backend into their own cells, each.
 Or she could reflect the microservices architecture in the Cells.
 
 Paisano has a first class concept of Cells.
@@ -170,21 +167,21 @@ By using these principles rather than a rigid opinionated structure, it also rem
 
 In summary, all these organization and typing principles enable:
 
-- Easy refactoring of your repository's namespace for devops artifacts
+- Easy refactoring of your repository's devops namespace
 - Intuitive grouping of functionality that encourages well-defined internal boundaries
-  - Thereby keeping your automation code clean and maintainable
+  - Allowing for keeping your automation code clean and maintainable
 - Making use of Block Types and the shared library to implement the DRY principle
 - Reasoning about the content of your repo through structured data
   - Thereby interesting user interfaces, such as a CLI, TUI or even a UI
-  - But also services such as (close to) zero config & self-updating CI
+  - As well as also services like a (close to) zero config, self-updating CI
 - Similar organizational principles help to lower the cost of context switching between different projects
 
 ### Standard's Block Types (DevOps Type System)
 
 As mentioned above, Standard exploits the Block Type abstraction to provide artifact types for the SDLC.
 Within the semantics of each Block Type, we implement shared functionality.
 This is designed to offer the user an optimized, audited implementation.
-It also saves the need to devise "yet another" local implementation of otherwise well-understood generic functionality, such as, for example the building of a package or the pushing of a container image.
+Alleviates the burdon of devising "yet another" local implementation of otherwise well-understood generic functionality, such as, the building of a package or the pushing of a container image.
 
 ### Standard's Cells (Function Library)
 

COMPARE.md

@@ -6,14 +6,14 @@ _Where appropriate, we compare with `divnix/paisano`, instead_.
 
 ### flake-utils
 
-`numtide/flake-utils` is a small & lightweight utility with a focus on generating flake file _outputs_ in accordance with the packaging use case built-in into the Nix CLI tooling.
+`numtide/flake-utils` is a small & lightweight utility with a focus on generating flake file _outputs_ in accordance with the packaging use case built into the Nix CLI tooling.
 
 Paisano, in turn, is an importer with a focus on _code organization_; it still plugs well into a `flake.nix` file, but also preserves its index function by keeping it clean.
 While you _can_ use it to match the schema that Nix CLI expects, it also enables more flexibility as it is not specially optimized for the Nix _package manager use case_.
 
 ### flake-parts
 
-`hercules-ci/flake-parts` is a component aggregator with a focus on a flake schema that is built-in into the Nix CLI tooling that makes use of the NixOS module system for composability and aggregation.
+`hercules-ci/flake-parts` is a component aggregator with a focus on a flake schema that is built into the Nix CLI tooling that makes use of the NixOS module system for composability and aggregation.
 
 Paisano, in turn, is an importer with a focus on _code organization_; it still plugs well into a `flake.nix` file, but also preserves its index function by keeping it clean.
 While you _can_ use it to match the schema that Nix CLI expects, it also enables more flexibility as it is not specially optimized for the Nix _package manager use case_.
@@ -24,12 +24,12 @@ However, in that role, it gives you back the freedom to use the output schema th
 Convergence towards the Flakes output schema is provided via the harvester family of functions (`winnow`, `harvest` & `pick`).
 Depending on the domain schema, it can be a _lossy_ convergence due the lesser expressivity of the flake output schema.
 
-Flake Parts aggregates bespoke use-case specific interfaces implemented in the module system DSL.
+Flake Parts aggregates bespoke use-case specific interfaces implemented in a domain specific language based on Nix (i.e. "the module system").
 Paisano, in turn, focuses on code organization along high level code boundaries connected by generic interfaces.
 
-The core tenet of Flake Parts is bespoke module system DSL interfaces for each use case.
+The core tenet of Flake Parts is domain specific interfaces for each use case.
 
-The core tenet of Paisano remains Nix' original functional style.
+The core tenet of Paisano remains Nix' original functional style paired with a function library.
 
 ### Devshell
 
@@ -45,7 +45,7 @@ Most languages are already covered.
 ### Bazel
 
 Bazel is similar to Nix in that it creates cross-language build graphs.
-However, it doesn't not guarantee reproducibility.
+However, it does not guarantee reproducibility.
 Currently it has more advanced build caching strategies: a gap that the Nix community is very eager to close soon.
 
 ### My CI/CD

PITCH.md

@@ -7,14 +7,14 @@ It is essential to have an idea of who they are, so let's introduce:
 Makes resources available in return for the expectation of future benefits.
 
 **_The Provider of Automation_**
-Sets up and maintains the automation alongside the SDLC.
-A helpful analogy would be the person who sets up and maintains the conveyor belt, which moves features to production.
+Sets up and maintains the automation along the SDLC.
+A helpful analogy would be the person who sets up and maintains the conveyor belt which moves features to production.
 
 **_The Consumer of Automation_**
-Consumes and co-maintaines the automation alongside the SDLC.
-A helpful analogy would be that this person not only uses and configures our conveyor belt, but is also capable of maintaining it.
+Consumes and co-maintaines the automation along the SDLC.
+A helpful analogy would be that this person not only uses and configures our conveyor belt, but is also capable of occasionally maintaining it.
 
-It is equally essential to have an understanding what they value, so let's try to get an overview.
+It is essential to have an understanding what they value, so let's try to get an overview.
 We'll make use of a high level value matrix with simple sentiment scores:
 
 - :heart_eyes: &rarr; <i>"absolutely love it!!!"</i>

ROADMAP.md

@@ -1,7 +1,6 @@
 # Roadmap
 
-The freestyle history of the project was productive at its time.
-But recently, it has been outgrowing its freedom to freestyle.
+The freestyle history of the project was productive during the alpha stage, but as the code stabilizes, so too must our processes.
 
 This roadmap gives an overview of the short and mid term direction that the project aims to take.
 
@@ -13,22 +12,22 @@ These help us to better understand the work spectrum associated with the project
 
 ##### Process Categories
 
-To run an _automation_ we have to _set it up_, first.
+To run _automation_ we have to _set it up_, first.
 We should keep that in mind when working on the backlog and therefore classify:
 
 - Setup
 - Automation
 
-Work packages that supports setup typically involve:
+For setup, besides function libraries, a variety of supporting material is crucial, such as:
 
-- Documentation & Setup Instructions
-- Pattern & Shared Mental Models
-- Quick Start Template
+- Documentation & Instructions
+- Patterns & Shared Mental Models
+- Quick Start Templates
 - Onboarding & Learning Content
 
 ##### Process Regions
 
-Per our [architectural overview](./ARCHITECTURE.md), we distinguishe these process regions:
+Per our [architectural overview](./ARCHITECTURE.md), we distinguish these process regions:
 
 - Development Environment
 - Build Pipeline
@@ -37,12 +36,12 @@ Per our [architectural overview](./ARCHITECTURE.md), we distinguishe these proce
 ##### Deliverable Types
 
 - Docs
-- CLI Commands or TUI functionality
+- CLI commands or TUI helpers
 - Integrations
-- Library Functions
+- Library functions
 - Block Types
-- Stable Interfaces
-- Community Outreach
+- Stable interfaces
+- Community outreach
 
 ## Milestone v1