Merge pull request #752 from grouville/docs_102/103_wording_improvement

docs: improve 102/103

docs/learn/102-dev.md

@@ -6,33 +6,32 @@ slug: /learn/102-dev
 
 ## Overview
 
-In this guide you will create your first Dagger environment from scratch,
+In this guide, you will create your first Dagger environment from scratch,
-and use it to deploy a React application to 2 locations in parallel:
+and use it to deploy a React application to two locations in parallel:
 a dedicated [Amazon S3](https://wikipedia.org/wiki/Amazon_S3) bucket, and a
 [Netlify](https://en.wikipedia.org/wiki/Netlify) site.
 
 ### Anatomy of a Dagger environment
 
-A Dagger environment contains all the code and data necessary to deliver a particular application in a particular way.
+A Dagger environment contains all the code and data necessary to deliver a particular application in a specific way.
-For example the same application might be delivered to a production and staging environment, each with their own
+For example, the same application might be delivered to a production and staging environment, each with its own configuration.
-configuration.
 
 An environment is made of 3 parts:
 
 - A _plan_, authored by the environment's _developer_, using the [Cue](https://cuelang.org) language.
 
-- _Inputs_, supplied by the environment's _user_ via the `dagger input` command, and written to a special file. Inputs may be configuration values, artifacts, or encrypted secrets.
+- _Inputs_, supplied by the environment's _user_ via the `dagger input` command and written to a particular file. Inputs may be configuration values, artifacts, or encrypted secrets.
 
-- _Outputs_, computed by the Dagger engine via the `dagger up` command, and recorded to a special directory.
+- _Outputs_, computed by the Dagger engine via the `dagger up` command and recorded to a particular directory.
 
-We will first develop our environment's _plan_, then configure its initial inputs, then finally run it to verify that it works.
+We will first develop our environment's _plan_, configure its initial inputs, then finally run it to verify that it works.
 
 ### Anatomy of a plan
 
-A _plan_ specifies, in code, how to deliver a particular application in a particular way.
+A _plan_ specifies, in code, how to deliver a particular application in a specific way.
 It is your environment's source code.
 
-Unlike regular imperative programs which specify a sequence of instructions to execute,
+Unlike regular imperative programs, which specify a sequence of instructions to execute,
 a Dagger plan is _declarative_: it lays out your application's supply chain as a graph
 of interconnected nodes.
 
@@ -56,13 +55,13 @@ Cue is a powerful declarative language by Marcel van Lohuizen. Marcel co-created
 If you are new to Cue development, don't worry: this tutorial will walk you through the basic
 steps to get started, and give you resources to learn more.
 
-In technical terms, our plan is a [Cue Package](https://cuelang.org/docs/concepts/packages/#packages). In this tutorial we will develop a new Cue package from scratch for our plan; but you can use any Cue package as a plan.
+In technical terms, our plan is a [Cue Package](https://cuelang.org/docs/concepts/packages/#packages). This tutorial will develop a new Cue package from scratch for our plan, but you can use any Cue package as a plan.
 
 ## Initial setup
 
 ### Install Cue
 
-Although not strictly necessary, for an optimal development experience we recommend
+Although not strictly necessary, for an optimal development experience, we recommend
 [installing a recent version of Cue](https://github.com/cuelang/cue/releases/).
 
 ### Prepare Cue learning resources
@@ -94,9 +93,9 @@ cd examples/todoapp
 
 Developing for Dagger takes place in a [Cue module](https://cuelang.org/docs/concepts/packages/#modules).
 If you are familiar with Go, Cue modules are directly inspired by Go modules.
-Otherwise, don't worry: a Cue module is simply a directory with one or more Cue packages in it. A Cue module has a `cue.mod` directory at its root.
+Otherwise, don't worry: a Cue module is simply a directory with one or more Cue packages in it. For example, a Cue module has a `cue.mod` directory at its root.
 
-In this guide we will use the same directory as the root of the Dagger workspace and the root of the Cue module; but you can create your Cue module anywhere inside the Dagger workspace.
+This guide will use the same directory as the root of the Dagger workspace and the Cue module, but you can create your Cue module anywhere inside the Dagger workspace.
 
 ```shell
 cue mod init
@@ -106,10 +105,9 @@ cue mod init
 
 Now we start developing our Cue package at the root of our Cue module.
 
-In this guide we will split our package in multiple files, one per component.
+In this guide, we will split our package into multiple files, one per component.
-But you can organize your package any way you want: the Cue evaluator simply merges together
+Thus, it is typical for a Cue package to have only one file. However, you can organize your package any way you want: the Cue evaluator merges all files from the same package, as long as they are in the same directory, and start with the same
-all files from the same package, as long as they are in the same directory and start with the same
+`package` clause...
-`package` clause. It is common for a Cue package to have only one file.
 See the [Cue documentation](https://cuelang.org/docs/concepts/packages/#files-belonging-to-a-package) for more details.
 
 We will call our package `multibucket` because it sounds badass and vaguely explains what it does.
@@ -125,10 +123,10 @@ mkdir multibucket
 
 The first component of our plan is the source code of our React application.
 
-In Dagger terms, this component has 2 important properties:
+In Dagger terms, this component has two essential properties:
 
 1. It is an _artifact_: something that can be represented as a directory.
-2. It is an _input_: something that is provided by the end user.
+2. It is an _input_: something that is provided by the end-user.
 
 Let's write the corresponding Cue code to a new file in our package:
 
@@ -143,7 +141,7 @@ import (
 src: dagger.#Artifact & dagger.#Input
 ```
 
-This defines a component at the key `src`, and specifies that it is both an artifact and an input.
+This code defines a component at the key `src`, and specifies that it is both an artifact and an input.
 
 ### Component 2: yarn package
 
@@ -168,11 +166,11 @@ Let's break it down:
 - `import ( "alpha.dagger.io/js/yarn" )`: import a package from the [Dagger Universe](../reference/universe/README.md).
 - `app: yarn.#Package`: apply the `#Package` definition at the key `app`
 - `&`: also merge the following values at the same key...
-- `{ source: src }`: set the key `app.source` to the value of `src`. This connects our 2 components, forming the first link in our DAG.
+- `{ source: src }`: set the key `app.source` to the value of `src`. This snippet of code connects our two components, forming the first link in our DAG
 
 ### Component 3: dedicated S3 bucket
 
-_FIXME_: this section is not yet available, because the [Amazon S3 package](https://github.com/dagger/dagger/tree/main/stdlib/aws/s3) does [not yet support bucket creation](https://github.com/dagger/dagger/issues/623). We welcome external contributions :)
+_FIXME_: this section is not yet available because the [Amazon S3 package](https://github.com/dagger/dagger/tree/main/stdlib/aws/s3) does [not yet support bucket creation](https://github.com/dagger/dagger/issues/623). We welcome external contributions :)
 
 ### Component 4: deploy to Netlify
 
@@ -191,13 +189,13 @@ site: "netlify": netlify.#Site & {
 }
 ```
 
-This is very similar to the previous component:
+This component is very similar to the previous one:
 
 - We use the same package name as the other files
 - We import another package from the [Dagger Universe](../reference/universe/README.md).
 - `site: "netlify": site.#Netlify`: apply the `#Site` definition at the key `site.netlify`. Note the use of quotes to protect the key from name conflict.
 - `&`: also merge the following values at the same key...
-- `{ contents: app.build }`: set the key `site.netlify.contents` to the value of `app.build`. This connects our components 2 and 3, forming the second link in our DAG.
+- `{ contents: app.build }`: set the key `site.netlify.contents` to the value of `app.build`. This line connects our components 2 and 3, forming the second link in our DAG.
 
 ### Exploring a package documentation
 

docs/learn/103-script.md

@@ -4,7 +4,7 @@ slug: /learn/103-script
 
 # Dagger 103: integrate custom shell scripts
 
-In this guide, you will learn how to incorporate your custom shell scripts into a Dagger environment. For example, to run integration tests before deployment; call a custom processing step; or any other custom task which you have already automated, and want to incorporate into your Dagger environment with minimal effort.
+In this guide, you will learn how to incorporate your custom shell scripts into a Dagger environment. For example, run integration tests before deployment; call a custom processing step; or any other custom task which you have already automated and want to incorporate into your Dagger environment with minimal effort.
 
 This section is not yet written. Help Dagger growing by suggesting content improvements.