creativecommons
[Feature] Improvements on repo Readme.md
Problem
As a beginner and new contributor to the Creative Commons Community, I made some mistakes while trying to install docker and clone the repo. After reading through the Readme.md, I took the first step under 'Docker compose setup' in the Readme.md and clicked on the link to install Docker. And then I had several failed attempts in starting up Docker.
After successfully setting up Docker, I made a mistake by attempting to clone the repo in Docker, because I did not properly understand the second instruction. Cloning the repo in Docker took so many hours and my PC even lagged behind for a bit.
Description
In this context, I suggest we add more descriptive guidelines in the Readme.md, by adding a few sides notes that state the main tools needed for the project and their uses. For instance; stating that Docker is just for background work and the code editor/IDE is where the cloning and main work should be done. This way, new contributors who are most likely beginners will be able to understand the steps and process better and avoid making mistakes.
Implementation
- [x] I would be interested and happy to implement this feature. -Under the 'Setting Up the Project' section, it will be nice to include: The three main tools you'll need on most projects here are:
Docker App (Docker does some heavy lifting, but it's mostly for background use) A code editor/IDE (VS Code, Sublime, Nova, etc.)(This is where the bulk of the work, like cloning your repo, and making your code changes, will be done) A command-line/terminal client (Terminal, iTerm2, etc.) (if your IDE doesn't have one) If you have all three of these tools, then you can proceed to the next steps below
Under Docker Setup, I feel like a more detailed step by step instructions should be added.
@possumbilities I will love to work on this, that's if no one is working on it.
@mildrette @dikehprosper Yes I created the issue so I could work on it. But if you have additional contributions That’s welcome too
I'm liking this idea, but I feel like the wording needs to be spelled out here (in the Issue, or in the conversation on this Issue) so that it can be helpful to newcomers, but not add accidental confusion in other ways.
@PreciousOritsedere do you have an exact idea of wording you want to use here?
It's also fine for others to comment here what they think would be best to write to add, and once we've all settled on something then we could move towards finalizing the Issue and getting it ready to have an appropriate related PR :)
Yes I have some ideas Under the 'Setting Up the Project' section, I wanted to include: The three main tools you'll need on most projects here are:
- Docker App (Docker does some heavy lifting, but it's mostly for background use)
- A code editor/IDE (VS Code, Sublime, Nova, etc.)(This is where the bulk of the work, like cloning your repo, and making your code changes, will be done)
- A command-line/terminal client (Terminal, iTerm2, etc.) (if your IDE doesn't have one)
If you have all three of these tools, then you can proceed to the next steps below
@possumbilities Also I have a recorded video of how to install Docker and clone the repo and also render it to the browser. If it's fine with you, I can make it available through a link that we could also add to the readme.md
@PreciousOritsedere that's very kind of you, but we generally try to keep documentation as text only as much as possible to keep the codebase light-weight and as accessible to everyone :)
Okay. That's noted. How about the suggestion I have updated the issue comment. Others can add more suggestions too :)
@PreciousOritsedere I think you should also include information for windows system users who are having a lot of problems setting up the docker container
If you need help documenting let me know so I can peach some ideas for you to open up a PR and this close the issue :)
Hi @possumbilities
On the wording, For languages, I'd use the second person pronoun, an active voice, and American spellings. I will also be using markdown for the texts, then I want to a more step-by-step approach on the main tools you'd need for your project, such as Docker App, a code editor (recommended will be Visual Studio Code, this will be used for version control and code changes). Additional info will be improved and more readable text for the solution wording, such as precise commands for the initialising and navigating project using docker.
@ImaJin14 thats a great suggestion. You can drop it here in the comments so @possumbilities can confirm that it’s okay for me to add it
@dikehprosper we prefer all documents not to have a gender pronoun so it is accessible to all pronouns!!!
You can refer to other project readme.md files to see how it was done:)
@ImaJin14 thats a great suggestion. You can drop it here in the comments so @possumbilities can confirm that it’s okay for me to add it
Okay for windows user I think it's better they set up the wsl module so as to use Linux on their windows os which will go a long way to reduce and simplify the use of docker:)
You'll need to run a test locally to be sure the link provided sets up the wsl feature correctly so they can go back to default setup process while using the Linux terminal with docker!!!
Do wait for @possumbilities review on my suggestions to the readme.md file
Also remove the code base under deployment so as not to raise confusion on how to sync your local repository with the remote repository!!!
@PreciousOritsedere @possumbilities @ImaJin14 This should be addressed too….For easy syncing…users can manually sync the fork on their GitHub pages with the source…then run “git pull” in the shell of their IDE … to update their codes on recent commits made
@PreciousOritsedere @possumbilities @ImaJin14 This should be addressed too….For easy syncing…users should manually sync the fork on their GitHub pages with the source…then run “got pull” in the shell of their IDE
The command is git pull...
@PreciousOritsedere @possumbilities @ImaJin14 This should be addressed too….For easy syncing…users should manually sync the fork on their GitHub pages with the source…then run “got pull” in the shell of their IDE
The command is git pull... Yeah was a typographical error I corrected already …thanks
@possumbilities There isn't any status label on this issue, does that mean it's ready for work and I can proceed to work on it and request a PR?
If it's ready for work, please can you assign it to me? @possumbilities
@ImaJin14 thats a great suggestion. You can drop it here in the comments so @possumbilities can confirm that it’s okay for me to add it
Okay for windows user I think it's better they set up the wsl module so as to use Linux on their windows os which will go a long way to reduce and simplify the use of docker:)
You'll need to run a test locally to be sure the link provided sets up the wsl feature correctly so they can go back to the default setup process while using the Linux terminal with docker!!!
Hi can you throw more light on this? preferably the wordings and steps, so we can all understand. Because I didn't have to run wsl, so maybe you could drop the steps here as a comment? and @possumbilities can review
@PreciousOritsedere @possumbilities @ImaJin14 This should be addressed too….For easy syncing…users can manually sync the fork on their GitHub pages with the source…then run “git pull” in the shell of their IDE … to update their codes on recent commits made
yes, I usually do this most times , I feel it's easier
hello @PreciousOritsedere are there more improvements to be done here? i would really love to contribute
Hi @Munnachienyi we need more details on what to add before the issue can be ready. You can help us out by suggesting what to add to the readme
@PreciousOritsedere I think it'll be good to remove all the data about how to fork your repo and make set it up locally and just used a link to the GitHub tutorials... That way we have fewer notes in the readme.md file and the user has access to alot of information about working with GitHub...
We're making plans to move some beginner documentation to a better resource. See this comment from Timid Robot on another repository: https://github.com/creativecommons/cc-legal-tools-app/issues/308#issuecomment-1281495855
This issue raises a valid concern: this repository/project assumes some skills and anyone without them is not helped. We will also be working to improve our introductory documentation (but I expect it will be referenced--not added to this repository).
I'm gonna leave this open for the time being, but in a status of blocked, anyone can feel free to keep commenting, but we'll likely move towards getting this guidance in a useful place, but that place may not necessarily be directly in the README.md file