all: fix grammar, typos, reformat tables #586

J4bbi · 2023-09-29T22:28:00Z

Description

This PR fixes obvious grammatical mistakes, typos and reformats some tables to make the markdown more readabe/correct.

Checklist

Ticks in all boxes and 🟢 on all GitHub actions status checks are required to merge:

Third-party code

If you've added third-party code (copy/pasted or new dependencies), please reach out to an architect.

Reminder

By using GitHub, you have already agreed to the GitHub’s Terms of Service including that:

You license your contribution under the same terms as the current repository’s license.
You agree that you have the right to license your contribution under the current repository’s license.

fenekku

Thank you so much for this! This must have been a gradual investment over time and we really appreciate it.

There is a couple of further adjustments I added. I will take another look after and then merge.

This will really level up the professionalism of the project. Thanks so much again!

fenekku · 2023-10-02T12:08:26Z

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

@@ -5,7 +5,7 @@ institution's logo. We are going to change InvenioRDM's default logo to your log

 ## Step-by-step

-**Step 1** - Take an *svg* file and copy it to your **local** static files.
+**Step 1** - Take a *svg* file and copy it to your **local** static files.


Hehe this is a tricky one 😺 , but an is probably the right one. "a" / "an" is actually based on "sound" of consonant / vowel rather than based on actual consonant / vowels. And this is especially true for acronyms. So we write "an FBI file", because "eff-bee-eye" and we should write "an svg file" because "ess-vee-gee"

See: https://www.merriam-webster.com/grammar/is-it-a-or-an

fenekku · 2023-10-02T12:12:18Z

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


👍 hard "h" for "high"

fenekku · 2023-10-02T12:14:05Z

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 our past


Suggested change

InvenioRDM is no different. The architecture is largely a byproduct our past

InvenioRDM is no different. The architecture is largely a byproduct of our past

and remove "we've faced" in next line as it's redundant.

fenekku · 2023-10-02T12:18:05Z

docs/develop/architecture/index.md

@@ -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 monolith application using something as old as a relational


Suggested change

InvenioRDM is a monolith application using something as old as a relational

InvenioRDM is a monolithic application using something as old as a relational

Grammar-wise this is probably the most correct. Tech discussions around this usually talk about the nouns directly ("monoliths"! "micro-services"!) rather than "x application". It does sound a little bit "harsher" because the reader spends more time on a bigger word that describes a bigger thing, so the effect is compounded. But that's just how it sounds. 🤷

fenekku · 2023-10-02T12:26:07Z

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 look-ups, which


"lookups" is good too. I want to say "lookups" is more common in computer science lingo, but unsure. So this one is a take it or leave it.

fenekku · 2023-10-02T12:54:01Z

docs/develop/getting-started/debugging.md


 To use the command you can follow the next steps:
- Add the statement in your code e.g
+- Add the statement in your code e.g.


Suggested change

- Add the statement in your code e.g.

- Add the statement in your code e.g.,

Won't do this for all, but you get the drift.

fenekku · 2023-10-02T12:54:47Z

docs/develop/getting-started/virtualenvs.md

@@ -24,7 +24,7 @@ programs (i.e. a distribution provides the ``python`` command).
 ### Distribution version

 Each distribution comes in multiple versions that's able to interpret the
-Python programming language - e.g Python 3.8, 3.9 etc.
+Python programming language - e.g. Python 3.8, 3.9 etc.


Suggested change

Python programming language - e.g. Python 3.8, 3.9 etc.

Python programming language - e.g., Python 3.8 and 3.9

also won't re-highlight those

fenekku · 2023-10-02T12:59:15Z

docs/maintenance/board-workflow.md

@@ -6,7 +6,7 @@ This guide is intended for maintainers and developers of InvenioRDM itself.

 **Scope**

-The guide covers the how we use the GitHub sprint boards during  development.
+The guide covers how we use the GitHub sprint boards during  development.


Suggested change

The guide covers how we use the GitHub sprint boards during development.

The guide covers how we use the GitHub sprint boards during development.

fenekku · 2023-10-02T13:00:48Z

docs/maintenance/release-management.md

@@ -86,7 +86,7 @@ For modules in ``vX.Y.Z``, the new version is ``v(X+1).0.0.dev0``.
 - Release Invenio-App-RDM (removing the pre-release suffix - e.g. ``dev0``).
 - Cookiecutter-Invenio-RDM:
    - Merge everything to ``master``.
-    - Create new version branch from ``master`` using the pattern ``vX.Y`` (e.g if Invenio-App-RDM is v1.0.0, the branch should be named ``v1.0``).
+    - Create new version branch from ``master`` using the pattern ``vX.Y`` (e.g. if Invenio-App-RDM is v1.0.0, the branch should be named ``v1.0``).


Suggested change

- Create new version branch from ``master`` using the pattern ``vX.Y`` (e.g. if Invenio-App-RDM is v1.0.0, the branch should be named ``v1.0``).

- Create a new version branch from ``master`` using the pattern ``vX.Y`` (e.g., if Invenio-App-RDM is v1.0.0, then the branch should be named ``v1.0``).

fenekku · 2023-10-02T13:06:45Z

docs/reference/metadata.md

 | ``pid`` | Object level information about the identifier needed for operational reasons. |

 Concept version PID:

-| Field |   Description   |
-|:-----:|:----------------|
+|     Field     | Description                                 |


Let's not bother with the centering. It's centered on display already, we can let the machine deal with it. This won't last the churn of editing I can tell you 😸 .

I've left the centering, just because it's more faff to revert it if that's okay

J4bbi · 2023-10-03T11:00:05Z

@fenekku , thanks for the review, I've responded to all your comments, and I also changed a couple of other thing I noticed

I removed the last sentence
"All of this can be further complicated if you run container images or virtual machines" from virtualenvs.md because I didn't think it added much value.

fenekku

Some last things and we can merge. Thanks again 👍 !

fenekku · 2023-10-03T12:59:39Z

docs/develop/architecture/requests.md

@@ -76,7 +76,7 @@ A request is conceptually modelled over the following state diagram:
 - **Expired** - The request expired without the creator or receiver taking action.
 - **Accepted** - The receiver accepted the request.
 - **Declined** - The receiver declined the request.
- **Deleted** - The unsubmitted request was deleted by the creator or system.
+- **Deleted** - The draft request was deleted by the creator or system.


Let's actually keep "unsubmitted" here to tie it back to "not yet submitted" above and sidestep any confusion with the concept of "drafts" elsewhere (invenio requests use a different mechanism than record drafts).

fenekku · 2023-10-03T13:03:08Z

docs/develop/architecture/requests.md

 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:
+Views over requests is a search filter applied in a given context. Currently, we have the following views:


Suggested change

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":

fenekku · 2023-10-03T13:03:35Z

docs/develop/architecture/requests.md

@@ -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.


Suggested change

There are however notable differences between pull/merge requests and requests in InvenioRDM.

There are, however, notable differences between pull/merge requests and requests in InvenioRDM.

fenekku · 2023-10-03T13:06:35Z

docs/develop/architecture/software.md

@@ -24,13 +24,13 @@ 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, as well as e.g., parsing arguments from an HTTP request (e.g., parsing the query string parameters).


Suggested change

*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.

fenekku · 2023-10-03T13:08:22Z

docs/develop/architecture/software.md


 *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?"



Just below is another fix to do: "where you code belongs" -> "where your code belongs"

fenekku · 2023-10-03T13:15:16Z

docs/develop/getting-started/virtualenvs.md

 Each distribution comes in multiple versions that's able to interpret the
-Python programming language - e.g Python 3.8, 3.9 etc.
+Python programming language - e.g., Python 3.8 and 3.9


Each distribution supports multiple version of the Python programming language e.g., Python 3.8 and Python 3.9

(can't create a suggestion for unmodified line, but let's reword it too)

fenekku · 2023-10-03T13:18:11Z

docs/develop/getting-started/virtualenvs.md


-This means that a virtual environment has it's own ``python`` and ``pip``
+This means that a virtual environment has its own ``python`` and ``pip``
 commands that are *enhanced aliases* to the distributions ``python`` and ``pip``


Don't know too much about that enhanced aliases business to be honest... I think cutting it at:

This means that a virtual environment has its own ``python`` and ``pip`` commands.

is good enough.

fenekku · 2023-10-03T13:19:15Z

docs/maintenance/release-management.md

@@ -86,7 +86,7 @@ For modules in ``vX.Y.Z``, the new version is ``v(X+1).0.0.dev0``.
 - Release Invenio-App-RDM (removing the pre-release suffix - e.g. ``dev0``).
 - Cookiecutter-Invenio-RDM:
    - Merge everything to ``master``.
-    - Create new version branch from ``master`` using the pattern ``vX.Y`` (e.g if Invenio-App-RDM is v1.0.0, the branch should be named ``v1.0``).
+    - Create a new version branch from ``master`` using the pattern ``vX.Y`` (e.g. if Invenio-App-RDM is v1.0.0, then the branch should be named ``v1.0``).


Suggested change

- Create a new version branch from ``master`` using the pattern ``vX.Y`` (e.g. if Invenio-App-RDM is v1.0.0, then the branch should be named ``v1.0``).

- Create a new version branch from ``master`` using the pattern ``vX.Y`` (e.g., if Invenio-App-RDM is v1.0.0, then the branch should be named ``v1.0``).

J4bbi · 2023-10-03T14:27:51Z

@fenekku , further comments addressed

fenekku · 2023-10-03T15:05:21Z

all: fix grammar, typos, reformat tables

d4000a3

fenekku reviewed Oct 2, 2023

View reviewed changes

address review comments

0e7ff2e

fenekku approved these changes Oct 3, 2023

View reviewed changes

address further review comments

c5d65e5

fenekku merged commit d085a2c into inveniosoftware:master Oct 3, 2023
1 check passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

all: fix grammar, typos, reformat tables #586

all: fix grammar, typos, reformat tables #586

J4bbi commented Sep 29, 2023

fenekku left a comment

fenekku Oct 2, 2023

fenekku Oct 2, 2023

fenekku Oct 2, 2023

fenekku Oct 2, 2023

fenekku Oct 2, 2023

fenekku Oct 2, 2023 •

edited

Loading

fenekku Oct 2, 2023

fenekku Oct 2, 2023

fenekku Oct 2, 2023

fenekku Oct 2, 2023

J4bbi Oct 3, 2023

J4bbi commented Oct 3, 2023

fenekku left a comment

fenekku Oct 3, 2023

fenekku Oct 3, 2023

fenekku Oct 3, 2023

fenekku Oct 3, 2023

fenekku Oct 3, 2023

fenekku Oct 3, 2023

fenekku Oct 3, 2023

fenekku Oct 3, 2023

J4bbi commented Oct 3, 2023

fenekku commented Oct 3, 2023

	InvenioRDM is no different. The architecture is largely a byproduct our past
	InvenioRDM is no different. The architecture is largely a byproduct of our past

	InvenioRDM is a monolith application using something as old as a relational
	InvenioRDM is a monolithic application using something as old as a relational

	- Add the statement in your code e.g.
	- Add the statement in your code e.g.,

	Python programming language - e.g. Python 3.8, 3.9 etc.
	Python programming language - e.g., Python 3.8 and 3.9

	The guide covers how we use the GitHub sprint boards during development.
	The guide covers how we use the GitHub sprint boards during development.

	- Create new version branch from ``master`` using the pattern ``vX.Y`` (e.g. if Invenio-App-RDM is v1.0.0, the branch should be named ``v1.0``).
	- Create a new version branch from ``master`` using the pattern ``vX.Y`` (e.g., if Invenio-App-RDM is v1.0.0, then the branch should be named ``v1.0``).

	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":

	There are however notable differences between pull/merge requests and requests in InvenioRDM.
	There are, however, notable differences between pull/merge requests and requests in InvenioRDM.

	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.

all: fix grammar, typos, reformat tables #586

all: fix grammar, typos, reformat tables #586

Conversation

J4bbi commented Sep 29, 2023

Description

Checklist

fenekku left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fenekku Oct 2, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

J4bbi commented Oct 3, 2023

fenekku left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

J4bbi commented Oct 3, 2023

fenekku commented Oct 3, 2023

fenekku Oct 2, 2023 •

edited

Loading