Improve README instruction clarity

[ctmbl]

Thank you for your warm welcome :) I have just sent a PR. I added section numbers and a table of contents. I also corrected some spelling and punctuation errors. You asked about clarity, and I have a few suggestions. First, I would suggest rephrasing a couple of sentences to make them sound more straightforward. For example, “The author assigned to the article will be the name of the authenticated user.” could be put as “Your username will appear as the author of the article.” Second, I think the deployment section could be structured a bit better. It’s a list of steps, but when you scroll through it, it is not clear. You need to read the details to understand what the paragraph is about. My suggestions would be to: change heading titles to start with a verb, use numbered lists, put prerequisites before the task description, and remove quote formatting. Below is an example of what I mean. As it’s not what you asked, I created a separate branch in my forked repository to work on additional changes. For me, it’s always an exercise. Later I can send another PR, and you can see if it is something you’d like to apply.

2.2 Production mode

The production mode allows to deploy the application on the server. To use it, you will need:

• docker
• docker-compose

a) Set up environment variables(.env file)

Before deploying the application, you need to set the environment variables as for development mode.

• From the root directory of the repository, do the following:

cp .env.example .env.production

b) Create SSL certificates

To set up HTTPS, you will need valid SSL certificates.

• If you deploy the app for the first time, follow these instructions:

1. Comment or delete the whole server section about 443 in the nginx/nginx.conf.template file.

- server {
- listen 443 default_server ssl http2;
- ...
- }

This step is required because the certificates don't exist yet, so they cannot be loaded in the nginx configuration.

Originally posted by @OlaPom in https://github.com/iScsc/iscsc.fr/issues/79#issuecomment-1520543338

[ctmbl]

@OlaPom If you're still interested in contributing to the repo you can now address these few suggestion you made (and that we really liked!)

[OlaPom]

Yes, I'd like to work on that:) You can assign the issue to me.

[ctmbl]

@OlaPom you're assigned :smile:

[ctmbl]

@OlaPom are you still interested in this one? :slightly_smiling_face:

[OlaPom]

Yes, I'm still interested (busy time lately, I'm sorry)! I already have a draft, but I need to write my comments to explain the suggestions. I should be able to send a draft PR this week.

Two things I can ask already: 1) Do you want to update the "repository structure" section? 2) What do you think about adding a screenshot to the section Functionalities > Create? This part is avaialble to authenticated users only, so it might be intersting to show what the website looks like to extrernal readers as well.

[ctmbl]

Yes, I'm still interested (busy time lately, I'm sorry)! I already have a draft, but I need to write my comments to explain the suggestions. I should be able to send a draft PR this week.

No pb was just asking 😉

Do you want to update the "repository structure" section?

if it's not up-to-date (and surely is) then yes you can!

What do you think about adding a screenshot to the section Functionalities > Create? This part is avaialble to authenticated users only, so it might be intersting to show what the website looks like to extrernal readers as well.

hmmm let me think, in theory it's a good idea, but currently the frontend, and basically the whole website is very early so it would have to be updated frequently, I don't know if it's worth the maintenance overhead Maybe yes but then, you should write something like "version 0.1.1" or something, and we'll update it from time to time

[ctmbl]

@OlaPom