all: fix grammar, typos, reformat tables

docs/customize/authentication.md

@@ -199,7 +199,7 @@ OAUTHCLIENT_REMOTE_APPS["keycloak"] = keycloak_remote_app
 ##### Multiple Keycloak authentication providers
 
 You might have the need to integrate multiple Keycloak authentication providers at the same time, to allow
-users to login with one or the other. You can "namespace" each remote application using a different
+users to log in with one or the other. You can "namespace" each remote application using a different
 value for the parameter `app_key`. In your `invenio.cfg`:
 
 ```python
@@ -281,7 +281,7 @@ OPENAIRE_APP_CREDENTIALS = dict(
 )
 ```
 
-In case you want use the sandbox environment, use ``openaire_aai.REMOTE_SANDBOX_APP`` instead
+In case you want to use the sandbox environment, use ``openaire_aai.REMOTE_SANDBOX_APP`` instead
 of ``openaire_aai.REMOTE_APP``.
 
 ### Login automatic redirection
@@ -314,8 +314,8 @@ USERPROFILES_READ_ONLY = True
 
 *Introduced in InvenioRDM v11*
 
-By default, users who login using an external authentication provider are `confirmed` and the e-mail confirmation
-is not sent any more.
+By default, users who log in using an external authentication provider are `confirmed` and the e-mail confirmation
+is not sent anymore.
 
 The only exception is the ORCID OAuth plugin: the user e-mail cannot be retrieved by this provider
 and the user must provide it when registering for the first time.
@@ -905,7 +905,7 @@ OAUTHCLIENT_LOGIN_USER_TEMPLATE = "invenio_saml/login_user.html"
 
 #### Multiple SAML authentication providers
 
-You might have the need to integrate multiple SAML authentication providers at the same time, to allow users to login
+You might have the need to integrate multiple SAML authentication providers at the same time, to allow users to log in
 with one or the other.
 You can define multiple SAML apps in your `invenio.cfg`:
 

docs/customize/look-and-feel/logo.md

@@ -9,7 +9,7 @@ institution's logo. We are going to change InvenioRDM's default logo to your log
 
 We'll use the [invenio white logo](https://github.com/inveniosoftware/cookiecutter-invenio-rdm/blob/master/%7B%7Bcookiecutter.project_shortname%7D%7D/static/images/logo-invenio-white.svg) as an example:
 
-``` bash
+```shell
 cp static/images/logo-invenio-white.svg static/images/my-logo.svg
 ```
 
@@ -22,10 +22,9 @@ cp static/images/logo-invenio-white.svg static/images/my-logo.svg
 
 **Step 3** - Use the `invenio-cli assets build` command:
 
-``` bash
+```shell
 invenio-cli assets build
-```
-``` console
+
 # Summarized output
 Collecting statics and assets...
 Collect static from blueprints.
@@ -55,7 +54,6 @@ In the browser, go to [https://127.0.0.1:5000/](https://127.0.0.1:5000) or refre
     If you do not see it changing, check in an incognito window; the browser might have cached the logo.
 
 
-
 ## Custom static files workflow
 
 This workflow stands for all `static/` files:

docs/customize/look-and-feel/theme.md

@@ -62,7 +62,7 @@ That's because `.less` files (and React files) always need to be transformed int
 
 ## Automatic re-build
 
-That way is to run `invenio-cli assets watch` in a separate terminal. This command watches for changes to assets and rebuilds them automatically. It run indefinitely until you cancel it via `<Ctrl+C>`.
+That way is to run `invenio-cli assets watch` in a separate terminal. This command watches for changes to assets and rebuilds them automatically. It runs indefinitely until you cancel it via `<Ctrl+C>`.
 
 It needs to "know" the assets already however. This means you still need to run `invenio-cli assets build` if you have added a new file to `assets/`.
 

docs/customize/upload_limits.md

@@ -5,7 +5,7 @@ Limiting the maximum size for file uploads can be desirable for a few reasons, e
 
 ## Invenio Configuration
 
-`Invenio-Files-REST` provides some [configuration values](https://invenio-files-rest.readthedocs.io/en/latest/configuration.html) configuration values that are relevant for limiting file uploads.
+`Invenio-Files-REST` provides some [configuration values](https://invenio-files-rest.readthedocs.io/en/latest/configuration.html) that are relevant for limiting file uploads.
 The most relevant ones are `FILES_REST_DEFAULT_MAX_FILE_SIZE` which limits the maximum size for *each* uploaded file (in bytes) and `FILES_REST_DEFAULT_QUOTA_SIZE` which limits the maximum overall size of *all* files uploaded per record (also in bytes).
 
 For instance, consider the case that the maximum file size is set to 10GiB, and the default quota is set to 30GiB.

docs/customize/vocabularies/index.md

@@ -13,7 +13,7 @@ Behind the scenes, fixtures are currently loaded in a 2-step process: first `inv
 Another behind the scenes note, `invenio-cli services setup` calls `pipenv run invenio rdm-records fixtures` to deal with fixtures. That command-line tool (part of the internal API and therefore subject to change) assesses if fixtures are already existing before submitting them to the task queue. This means, it can be used to **add** new fixtures to your instance by being run again later which can be useful to add new subjects. It won't override/update previously existing fixtures.
 
 !!! warning "Unsupported cases"
-    There is no moment between database creation and fixture loading when you can create database entries (e.g., a role) and then use them for your fixtures. However, you can still create roles and assign them to users manually with `invenio` commands. We hope to make loading specific fixtures independent from each other and updating existing fixtures possible in the future.
+    There is no moment between database creation and fixture loading when you can create database entries (e.g., a role) and then use them for your fixtures. However, you can still create roles and assign them to users manually with `invenio` commands. We hope to make loading specific fixtures independent of each other and updating existing fixtures possible in the future.
 
 ## The app_data/ folder
 

docs/customize/vocabularies/names.md

@@ -11,7 +11,7 @@ You can find information behind the design and usage of the vocabulary in
 
 A _Name_ record contains:
 
-- The name of the author splitted in `family name` and `given name`, or a
+- The name of the author split in `family name` and `given name`, or a
   single `name` attribute with the full name formatted as
   `<family name>, <given name>`. Note that if `family name` and `given name`
   are present they will overwrite `name`.

docs/deploy/index.md

@@ -1,6 +1,6 @@
 # Deployment
 
-This guide is meant to give an high-level overview of deployment techniques and tips
+This guide is meant to give a high-level overview of deployment techniques and tips
 when planning how to deploy InvenioRDM.
 
 !!! info "Read the infrastructure architecture first!"
@@ -67,15 +67,15 @@ scope of this documentation.
 ## Services
 
 When deploying InvenioRDM, you can choose to install, securely configure and
-maintain yourself the services (such as the database, the search engine, etc..)
+maintain yourself the services (such as the database, the search engine, etc.)
 services, or use third party providers. For example, the three cloud providers
 mentioned above (AWS, GC, and Azure) can provide most of the services. If you
 choose to deploy them yourself you will need to deep-dive and get experienced
 in the following topics:
 
 - Persist your data, and enable periodic backups. This includes the relational
 database, the search indices and the files.
-- Queue persistence (RabbitMQ) to avoid loosing tasks in case the service fails.
+- Queue persistence (RabbitMQ) to avoid losing tasks in case the service fails.
 - High availability, many of the services can be deployed redundantly. Note
 that most of the cloud providers offer this option or have an established SLA.
 - Secrets handling. Most of the services require credentials to connect. It is
@@ -107,7 +107,7 @@ means that your application code will change and versioning will help you to
 control which code is actually deployed. At CERN, we use GitHub tags/release
 for each version (e.g. v1.0.0).
 
-If you are using container for the deployment, you can automate the image
+If you are using containers for the deployment, you can automate the image
 build with for example [GitHub actions](https://github.com/features/actions)
 (or any other CI tool). In addition, some PaaS platforms have the capabilities
 to detect when a new image for a certain tag (e.g. `production`) has changed

docs/develop/architecture/communities.md

@@ -30,8 +30,8 @@ communities to ensure a consistent user experience across all communities.
 A community roles translates into a set of permissions. The roles are
 configurable to ensure that they can be tailored to the needs of an instance,
 as well as allow for customizations. For example, one instance might want to use
-"curator" and another instance wants to use "editor" as a role because it adjust better
-to their use cases.
+"curator" and another instance wants to use "editor" as a role because it suits 
+their use cases better.
 
 By default the following community roles are defined:
 

docs/develop/architecture/index.md

@@ -23,11 +23,11 @@ projects, prior history and practices.
 
 **Evolving**
 
-InvenioRDM is no different. The architecture is largely a by product our past
+InvenioRDM is no different. The architecture is largely a byproduct of our past
 experiences and challenges we've faced. The architecture as described here, is
 not meant to be final answer, but rather an evolving architecture that adapts
 and improve over time. You also won't find the answer to all your question. As
-we work with the architecture, we identify short comings, missing things and concepts
+we work with the architecture, we identify shortcomings, missing things and concepts
 that could be better defined.
 
 **Past experiences and challenges**
@@ -43,7 +43,7 @@ By no means have we solved all of these, and any software project out there is l
 
 ### Why not X?
 
-InvenioRDM is a monolith application using something as old as an relational
+InvenioRDM is a monolithic application using something as old as a relational
 database system, thus we sometimes get asked questions like why not use microservices, why not serverless
 and why not use NoSQL, so here's an attempt to give some vague answers.
 

docs/develop/architecture/infrastructure.md

@@ -90,7 +90,7 @@ are usually highly reliable as compared to some NoSQL solutions.
 
 **Primary key lookups**
 
-Most access from Invenio to the database is via primary key look ups, which
+Most access from Invenio to the database is via primary key lookups, which
 are usually very efficient in database. Search queries and the like are all
 sent to the search engine cluster which can provide much better performance
 than a database.

docs/develop/architecture/records.md

@@ -22,9 +22,9 @@ The record data model is used to describe **a resource**. Examples of resources
 include e.g. journal articles, datasets, posters, videos, images, software and
 more. Some properties of resources:
 
-- A resource may exists in one or more versions.
+- A resource may exist in one or more versions.
 - A resource version has its own persistent identifiers and bibliographic
-  metadata (e.g. title, publication date, creator list etc may be different
+  metadata (e.g. title, publication date, or creator list may be different
   between versions).
 - All versions of a resource should be accessible and editable.
 
@@ -79,8 +79,8 @@ and save partial changes prior to being published.
 
 There's three different types of drafts:
 
-- **New draft**: The initial draft when no record versions has been published.
-- **Edit draft**: A draft of an published record version (used when editing an
+- **New draft**: The initial draft when no record versions have been published.
+- **Edit draft**: A draft of a published record version (used when editing an
   already published record)
 - **Next draft**: A draft without a published record version that is not the
   initial draft.
@@ -113,14 +113,14 @@ unordered child nodes. This means there is **no order** on record versions.
 
 One record version is designated as the latest version tracked by this
 state so that it's possible to show only the latest version of a record. It
-also keep tracks of which is the latest draft/next draft if they exists.
+also keeps track of which is the latest draft/next draft if they exist.
 
 Lastly, an integer index is incremented every time a new record version is
 created.
 
 The reason that we do not define an order on record versions is because
-multiple different orders may be relevant. A version history may no
-necessarily be linear so it can make sense to order by version number,
+multiple different orders may be relevant. A version history may not
+necessarily be linear, so it can make sense to order by version number,
 publication date or order in which the record version was created.
 
 ## Files
@@ -208,7 +208,7 @@ allowed to be used as
 The request itself follows the documented request states and transitions as
 documented under [requests](requests.md#statuses).
 
-The draft goes through it's own states as shown below:
+The draft goes through its own states as shown below:
 
 ![Draft review state diagram](../img/review-states.svg)
 

docs/develop/architecture/requests.md

@@ -166,13 +166,13 @@ build grant tokens both from:
 - a required need: e.g. a request requiring needs to grant access.
 - a provided need: e.g. an identity providing needs.
 
-This provides an for efficient searches when you serialize the required grants
+This provides efficient searches when you serialize the required grants
 into the indexed request, and when searching, you filter requests to the grants
 provided by the identity.
 
 ## Views
 
-Views over requests is a search filter applied in a given context. Currently we have the following views:
+Requests can be viewed in different contexts which map to appropriate search filters. Currently, we have the following views:
 
 - User view - view specific to a given user.
     - Requests where the user is the creator (e.g. submissions)
@@ -194,7 +194,7 @@ We imagine that requests can later be extended with features such as:
 
 A lot of the inspiration to the requests module comes from collaborative source code platforms like GitHub and GitLab and their pull/merge requests features. Other inspiration comes from user support systems like UserVoice.
 
-There are however notable differences between between pull/merge requests and requests in InvenioRDM.
+There are, however, notable differences between pull/merge requests and requests in InvenioRDM.
 Pull/merge requests is always made against a specific repository, and thus naturally *belong* to a given repository. This means that they are accessible on a single URL endpoint and permissions are conceptually somewhat easy to understand.
 
 Requests in InvenioRDM however makes sense from multiple endpoints depending on who is looking and the context they are doing it in.

docs/develop/architecture/runtime.md

@@ -57,7 +57,7 @@ way Flask allows you to build modular applications is via *blueprints*.
 In above example we have a small blueprint with just one *view*
 (``my_user_agent``), which returns the browser's user agent sting.
 
-This blueprint is *registered* on the *Flask application*. This allow you
+This blueprint is *registered* on the *Flask application*. This allows you
 to reuse the blueprint in another Flask application.
 
 ### Flask extensions

docs/develop/architecture/software.md

@@ -10,7 +10,7 @@ The guide provides a high-level overview of the core software architecture of In
 
 ## Layers
 
-InvenioRDM has a layered architecture that consistent of three layers:
+InvenioRDM has a layered architecture that consists of three layers:
 
 - Presentation layer
 - Service layer
@@ -24,17 +24,17 @@ The diagram below shows a simplified view of the data flow in the architecture.
 
 ![Architecture layers](../img/architecture.svg)
 
-*The presentation layer* parses incoming requests and routes them to service layer. This involves sending and receiving data in multiple different formats and translating these into an internal representation, as well as e.g. parsing arguments from an HTTP request (e.g parsing the query string parameters).
+*The presentation layer* parses incoming requests and routes them to service layer. This involves sending and receiving data in multiple different formats and translating these into an internal representation. For instance, this includes parsing arguments from an HTTP request (e.g., parsing the query string parameters).
 
-*The service layer* is completely independent from the presentation layer and can be used by many different presentation interfaces such as REST APIs, CLIs, Celery tasks. The service layer contains the overall control flow and is responsible for e.g. checking permissions and performing semantic data validation.
+*The service layer* is completely independent of the presentation layer and can be used by many different presentation interfaces such as REST APIs, CLIs, Celery tasks. The service layer contains the overall control flow and is responsible for e.g. checking permissions and performing semantic data validation.
 
 *The data access layer* is responsible for ensuring data integrity, harmonizing data access to different storages as well as fetching and storing the data in the underlying systems.
 
-The data flow between the layers is strictly limited to some few well-defined objects to ensure a clean separation of concerns. The presentation layer communicates with the service layer via a e.g. a record projection (i.e. a view of a record localised to a specific identity). The service layer communicates with the data access layer via e.g. a record entity that provides data abstraction, syntactic data validation, and a strong programmatic API.
+The data flow between the layers is strictly limited to some few well-defined objects to ensure a clean separation of concerns. The presentation layer communicates with the service layer via a record projection (i.e. a view of a record localised to a specific identity). The service layer communicates with the data access layer via a record entity that provides data abstraction, syntactic data validation, and a strong programmatic API.
 
 !!! tip "Tip: Where do you belong?"
 
-    A key question you should always ask yourself when designing or writing code is where you code belongs in the architecture:
+    A key question you should always ask yourself when designing or writing code is where your code belongs in the architecture:
 
     - Is it a presentation, service, or data access layer object?
     - Is the object crossing boundaries between layers?
@@ -65,12 +65,12 @@ The data access layer serves two purposes:
 
 - Provide a strong programmatic API that produce a clean, simple and reliable
   control flow in the service layer.
-- Persist our business objects on data storage in an reliable and performant
+- Persist our business objects on data storage in a reliable and performant
   way.
 
 !!! tip "Tip: Messy service layer?"
 
-    If you service layer code looks messy, likely you need to work on your data
+    If your service layer code looks messy, you may need to work on your data
     access layer.
 
     A typical example is the service layer doing data-wrangling with
@@ -137,7 +137,7 @@ The search mappings define how records are indexed and made searchable. Records
 
 Dumpers are responsible for dumping and loading prior to storing/fetching records on secondary storage (e.g. the search index), and play a key role for harmonizing data access to records from primary and secondary storages.
 
-Dumpers are specific to a secondary storage system (e.g. an search dumper, a file dumper, ...).
+Dumpers are specific to a secondary storage system (e.g. a search dumper, a file dumper, ...).
 
 The dump and load of a dumper MUST be idempotent - i.e. ``record == Record.load(record.dump())``. This ensures that independently of if a record was retrieved from primary or secondary storage, it has the same data and works in the same manner.
 
@@ -341,7 +341,7 @@ The resource config are used for dependency injection to
 
 ## Performance considerations
 
-Performance is of very high importance for InvenioRDM. There's however often
+Performance is of very high importance for InvenioRDM. There are however often
 trade-offs to be made.
 
 **Query vs indexing speed**
@@ -350,7 +350,7 @@ For InvenioRDM query speed is more important that fast indexing speeds. This mea
 we'll sometimes denormalize data to have high enough query speed. Once we denormalize
 data we immediately must also deal with stale data and cache invalidation.
 
-The version counter on on all records is instrumental in being able to manage
+The version counter on all records is instrumental in being able to manage
 the speed.
 
 **Database vs search engine**