Improve copywriting for top level elements

source/contribute/commit-messages.md

@@ -2,11 +2,11 @@
 
 ## Variable name changes
 
-To avoid OpenFisca users to be surprised by a non expected variable renaming breaking their code, we use standard commit messages when renaming a variable. The syntax is formalized below. It must be respected precisely, to allow automatic information extraction.
+To avoid OpenFisca users being surprised by the unexpected renaming of a variable that breaks their code, we use standard commit messages when renaming a variable. The syntax is formalised below. It must be respected precisely, to allow automatic information extraction.
 
 ### Renaming
 
-Renaming one or several variables will be notified by a commit message with the following syntax, **on one independent line per renamed variable**:
+Renaming one or several variables will be notified by a commit message that utilises **one independent line per renamed variable** with the following syntax:
 
 ```text
 Rename former_name to new_name
@@ -16,7 +16,7 @@ No other information must appear on this line.
 
 ### Introducing
 
-Introducing one or several new variables will be notified by a commit message with the following syntax, **on one idependant line per created variable**:
+Introducing one or several new variables will be notified by a commit message that utilises, **one separate line per created variable** with the following syntax:
 
 ```text
 Introduce new_name
@@ -26,7 +26,7 @@ No other information must appear on this line.
 
 ### Deprecating
 
-If a variable must not be used anymore, it will be notified by a commit message with the following syntax, **on one idependant line per deprecated variable**:
+If a variable must not be used anymore, it will be notified by a commit message that utilises **one separate line per deprecated variable** with the following syntax:
 
 ```text
 Deprecate former_name

source/contribute/developer-guide.md

@@ -2,10 +2,17 @@
 
 ## Source code repositories
 
-The OpenFisca project is distributed across many Git repositories:
+OpenFisca is distributed across many Git repositories. There are two types of repositories, those shared by everyone and country/jurisdiction specific repositories.
+
+Here are some of the main repositories shared by everyone:
 
 * [OpenFisca-Core](https://github.com/openfisca/openfisca-core)
-* [OpenFisca-France](https://github.com/openfisca/openfisca-france)
+* [Country-Template](https://github.com/openfisca/country-template)
+* [Legislation-Explorer](https://github.com/openfisca/legislation-explorer)
+* [OpenFisca-Survey-Manager](https://github.com/openfisca/openfisca-survey-manager)
+* [OpenFisca Documentation (this site)](https://github.com/openfisca/openfisca-doc)
+
+These can all be found at [https://github.com/openfisca](https://github.com/openfisca).
 
 ## Debugging code
 
@@ -43,7 +50,7 @@ To profile the execution of a portion of code, wrap it with these lines:
 ```
 
 Each time you call the endpoint a `result.profile` file is written.
-To prevent it to be overwritten, generate a dynamic name with [`tempfile.mkstemp`](https://docs.python.org/2/library/tempfile.html#tempfile.mkstemp).
+To prevent it from being overwritten, generate a dynamic name with [`tempfile.mkstemp`](https://docs.python.org/2/library/tempfile.html#tempfile.mkstemp).
 
 Then you can use the [runsnakerun](http://www.vrplumber.com/programming/runsnakerun/) GUI to inspect the profile data.
 

source/contribute/documentation.md

@@ -6,7 +6,7 @@ and the source is hosted on this GitHub repository:
 
 ## Collaborative editing
 
-Everybody can participate to the redaction of the documentation.
+Every reader is encouraged to participate in the improvement of the documentation.
 
 On each page there is a link named "Edit this page".
 Just click on it and you'll jump on GitHub on the Markdown source file of the page.

source/contribute/extensions.md

@@ -1,6 +1,6 @@
 # OpenFisca extensions
 
-Extensions allow you to define new variables or parameters for a tax and benefit system, while keeping their code separated from the main country package. They can only _add_ variables and parameters to the tax and benefit system: they cannot _modify_ or _neutralize_ existing ones.
+Extensions allow you to define new variables or parameters for a tax and benefit system, while keeping their code separated from the main country package. They can only _add_ variables and parameters to the tax and benefit system: they cannot _modify_ or _neutralise_ existing ones.
 
 They are for instance used to code local benefits.
 
@@ -28,4 +28,4 @@ All python files located directly in `{extension_name}/` are imported in the tax
 
 The syntax of the formulas within extension python files is the same than in the general country package formulas (e.g. `from openfisca_france.model.base import *`).
 
-Variables inside an extension should not have the same name than any existing formula, nor than any formula in another extension being used.
+Variables inside an extension should not have the same name as any existing formula, nor as any formula in another extension being used.

source/contribute/guidelines.md

@@ -1,6 +1,6 @@
 # Contributor guidelines
 
-The OpenFisca project follows the [GitHub Flow](https://guides.github.com/introduction/flow/).
+OpenFisca follows the [GitHub Flow](https://guides.github.com/introduction/flow/).
 
 Each Python package uses [Semantic Versioning](http://semver.org/).
 
@@ -20,15 +20,17 @@ Each OpenFisca repository has its own issues. See [OpenFisca repositories](https
 - If you modify/create/delete a simulation variable, please follow the [commit message rules](commit-messages.md).
 - When adding new variables, please consider the [naming guidelines](variables-naming.md).
 - Your code should be tested, if feasible:
-  + bugfixes should include regression tests
-  + new behavior should at least get minimal exercise
+  + bug fixes should include regression tests
+  + new behaviour should at least get minimal exercise
 - Use atomic commits, in particular try to isolate "code-cleanup" commits
 
 ### Opening a Pull Request
 
+> Note: It is the intention to generally rename `master` branches across OpenFisca to `main` in accordance with industry practice.
+
 - All code contributions are submitted via a Pull Request towards `master`. The `master` branches are thus [protected](https://help.github.com/articles/about-protected-branches/).
 - Opening a Pull Request means you want that code to be merged. If you want to only discuss it, send a link to your branch along with your questions through whichever communication channel you prefer.
-- If the Pull Request depends on another opened Pull Request on another repository (like OpenFisca-Core/OpenFisca-France), the requirements should be updated in the dependent project via its `setup.py`.
+- If the Pull Request depends on another opened Pull Request on another repository (like Core or some country model), the requirements should be updated in the dependent project via its `pyproject.toml` (or `setup.py` for older codebases).
 
 It is considered a good practice to begin the name of the pull request with a verb in the present imperative tense:
 
@@ -59,14 +61,13 @@ Due to a `pip` limitation, it is required to increment the major version number
 
 #### Peer reviews
 
-Pull requests should generally be **reviewed** by someone else than their authors.
+Pull requests should be **reviewed** by someone other than their authors.
 
 This is mandatory for:
 
 - Any Pull Request with **breaking changes** on `openfisca-france`, `openfisca-web-api`.
 - Any Pull Request bringing **new features**, if these features are not relative to a specific scope.
   + Adding a new route to the API **requires** a review.
-  + A review is yet not mandatory to add a new formula to social contributions in `openfisca-france`. It is though recommended.
 
 To help reviewers, make sure to add to your PR a **clear text explanation** of your changes.
 

source/contribute/language.md

@@ -4,7 +4,7 @@ The development language is English. All comments and documentation in common re
 
 ## Country-specific repositories
 
-Some repositories define the tax and benefit system of a specific country. In such cases, the language used throughout issues and pull requests should be one of the native ones of that country.
+Some repositories define the tax and benefit system of a specific country. In such cases, the language used throughout issues and pull requests should be one of the native languages of that country.
 
 For instance, `openfisca-france` issues and pull-requests should be written in French.
 

source/contribute/semver.md

@@ -31,4 +31,4 @@ It is thus crucial to determine whether your changes are **backwards-compatible*
 - Renaming or deprecating a variable.
 - Changing the default value of a variable.
 - Deprecating a parameter.
-- Changing the sctructure of the parameter tree.
+- Changing the structure of the parameter tree.

source/contribute/variables-naming.md

@@ -2,7 +2,7 @@
 
 ## General philosophy
 
-The discussion below is concerned with naming the variables of a country package. In that case, the ["local language rule"](language.md) applies, and the appropriate language for modeling the domain is one of the native ones of the modeled country. We consider each tax, collecting organism and country regulation, and so on, as a domain-specific term. In the same fashion, well-known abbreviations of these domain-specific terms are accepted.
+The discussion below is concerned with naming the variables of a country package. In that case, the ["local language rule"](language.md) applies, and the appropriate language for modelling the domain is one of the native ones of the modelled country. We consider each tax, collecting organism and country regulation, and so on, as a domain-specific term. In the same fashion, well-known abbreviations of these domain-specific terms are accepted.
 
 OpenFisca variables names should, as much as possible, be understandable by an external contributor who is **curious** about the country's tax and benefit system, **without necessarily being an expert**.
 
@@ -18,23 +18,20 @@ A particular effort should be made on variables that are likely to be reused.
 
 #### Bad naming
 
-- `vat_sub1`: In English-speaking countries VAT would unambiguously refer to Value Added Tax, but the addition of a suffix for technical purposes (e.g. an intermediate step in the computation) should in
-general be avoided. A better name might be `vat_on_exports` (assuming this is the intermediate step's
-meaning).
-- `cpstd`. Here the acronym might mean "Company Paid Short-Term Disability", but this acronym is not widely used or recognizable, and will not be found in a web search. Using a longer name is preferable.
+- `vat_sub1`: In English-speaking countries VAT would unambiguously refer to Value Added Tax, but the addition of a suffix for technical purposes (e.g. an intermediate step in the computation) should in general be avoided. A better name might be `vat_on_exports` (assuming this is the intermediate step's meaning).
+- `cpstd`. Here the acronym might mean "Company Paid Short-Term Disability", but this acronym is not widely used or recognisable, and will not be found in a web search. Using a longer name is preferable.
 
 ## Do's and don'ts
 
 ### Acronyms
 
-Acronyms are OK as long as they are broadly accepted and their meaning is quickly findable online. A good
-test for "findable" is that a web search _from the relevant country_ should turn up the intended meaning as the first or second hit.
+Acronyms are OK as long as they are broadly accepted and their meaning is quickly findable online. A good test for "findable" is that a web search _from the relevant country_ should turn up the intended meaning as the first or second result.
 
 #### Good naming
 
 - `VAT` (Value Added Tax, near-universal except in France)
 - `EBITDA` (tax, unambiguous)
-- `RSA` (French, social benefit rather than cryptography, recognizable in context)
+- `RSA` (French social benefit rather than cryptography, recognisable in context)
 
 #### Bad naming
 
@@ -90,4 +87,4 @@ This is often seen when aggregating from the individual level to e.g. the househ
 
 ## Legacy
 
-Some existing models (such as the France model, grown over several years) do not respect all the guidelines presented here. These guidelines may also evolve with improvements to the underlying computation engine (such as namespacing or improved approaches to aggregation and other relations between entity and group values). Since variables and parameters represent the external API of a model, and excessive migration labor may discourage the users of an API, it is preferable to avoid global renamings. However, new names should be compliant with these guidelines, and legacy ones should be improved progressively and opportunistically. Communicating your standards to contributors is an important part of maintaining your model.
+Some existing models (such as the France model, grown over several years) do not respect all the guidelines presented here. These guidelines may also evolve with improvements to the underlying computation engine (such as namespacing or improved approaches to aggregation and other relations between entity and group values). Since variables and parameters represent the external API of a model, and excessive migration labour may discourage the users of an API, it is preferable to avoid global renaming. However, new names should be compliant with these guidelines, and legacy ones should be improved progressively and opportunistically. Communicating your standards to contributors is an important part of maintaining your model.

source/find-help.md

@@ -16,14 +16,14 @@ The following prefixes are used before channel names to increase discoverability
 
 The following suffix conventions are used on tax and benefit system models by OpenFisca for better clarity:
 
-- Channels that centralize discussion around a specific tax and benefit system are suffixed with `-system`.
+- Channels that centralise discussion around a specific tax and benefit system are suffixed with `-system`.
  _For example- `france-system`_.
 *Note: If the full name is too long for the Slack channel character limit, then a shortened version of the name is used.
 
-- Channels that centralize discussions around extensions to tax and benefit systems are given that system’s module name, followed by `-ext-` and an identifier for that extension.
+- Channels that centralise discussions around extensions to tax and benefit systems are given that system’s module name, followed by `-ext-` and an identifier for that extension.
 _For example- `france-ext-paris`_.
 
-- Channels for the system-specific groups are campfires around which some specific organizations of contributors to a tax and benefit system gather. When a country becomes large enough, it so often happens that several contributors work concurrently on different parts of the system, and the main `-system` channel becomes unreadable. These channels are then modified by the system’s module name, followed by `-org-` and an identifier for that group. _For example `france-org-gouv`_.
+- Channels for the system-specific groups are campfires around which some specific organisations of contributors to a tax and benefit system gather. When a country becomes large enough, it so often happens that several contributors work concurrently on different parts of the system, and the main `-system` channel becomes unreadable. These channels are then modified by the system’s module name, followed by `-org-` and an identifier for that group. _For example `france-org-gouv`_.
 
 ## Contact