p5.js-website
p5.js-website copied to clipboard
processing
Redundant "Getting Started" tutorials in several reference files
The same process to Getting Started with the repo has been described in
- README.md - a bit short though
- Adding examples.md - a bit long
- i18n contribution.md - the most verbose, and very beginner friendly.
Moreover, the file structure contained in the i18n file is pretty much a duplicate of the one in README. I would suggest:
- moving the "Getting Started" parts in i18n file to its own separate file, and linking to it from all the three other files.
- Deleting the section on file structure from i18n, and linking to the one in README in it.
Thoughts? I am happy to work on this if approved.
@GaurangTandon since the steps are just a few, I think it might be easier for beginners if we just replicate these across files consistently so they don't have to click through multiple links to get started.
@lmccart I understand, but, it adds redundancy which makes maintainability harder. Also, since these steps are only taken once for the repo, if the person has already forked and cloned the repo for i18n work, they would still have the repo ready adding examples or any other work :) So, they won't need to click multiple links anyway.
@GaurangTandon ok I see your point. 👍 I would say please go ahead and make the change. @limzykenneth do you have thoughts here?
I think it's good to consolidate initial setup stuff in one place but for "initial setup" I'm thinking more just mentioning cloning the repo, npm install then grunt server to build the site and run it (which will be in README.md).
Any additional steps, even if they are required once only, for creating examples or i18n work etc should be isolated into their own file, that includes explaining file structures, as i18n and examples uses different file structures and different build steps (assemble vs just copying) so there's not need to know both to do one of them.
In principle I would like to see that the initial barrier to entry be as minimal as possible so to keep the information in README.md sparse but enough to build the website, then if someone wants to work on a specific task just read the guide for that type of task.
