Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve README instruction clarity #106

Open
ctmbl opened this issue May 19, 2023 · 7 comments
Open

Improve README instruction clarity #106

ctmbl opened this issue May 19, 2023 · 7 comments
Assignees
Labels
documentation Improvements or additions to documentation good first issue Good for newcomers Priority: Low The Issue will be address only if other tasks are done

Comments

@ctmbl
Copy link
Contributor

ctmbl commented May 19, 2023

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 #79 (comment)

@ctmbl
Copy link
Contributor Author

ctmbl commented May 19, 2023

@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!)

@ctmbl ctmbl added documentation Improvements or additions to documentation good first issue Good for newcomers Priority: Low The Issue will be address only if other tasks are done labels May 22, 2023
@OlaPom
Copy link
Contributor

OlaPom commented May 23, 2023

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

@amtoine amtoine assigned amtoine and OlaPom and unassigned amtoine May 23, 2023
@ctmbl ctmbl moved this from Backlog to Todo in iScsc website Jun 2, 2023
@ctmbl
Copy link
Contributor Author

ctmbl commented Jun 2, 2023

@OlaPom you're assigned 😄

@ctmbl
Copy link
Contributor Author

ctmbl commented Jun 26, 2023

@OlaPom are you still interested in this one? 🙂

@OlaPom
Copy link
Contributor

OlaPom commented Jul 4, 2023

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
Copy link
Contributor Author

ctmbl commented Jul 4, 2023

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
Copy link
Contributor Author

ctmbl commented Jul 4, 2023

@OlaPom

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation good first issue Good for newcomers Priority: Low The Issue will be address only if other tasks are done
Projects
Status: Todo
Development

No branches or pull requests

3 participants