We can upgrade the readability of the codes in our repo’s by making some subtle yet important changes,
- Improve efficiency of the workflow by making the codes more readable.
- Help new contributors get started.
- Give an idea about what features/software’s used in each repo’s or (files/folders) .
- We can supply information to a different developer etc.**
1.Specifying features or software’s used in files ex: add in readme, mustache JS is used for these files.
2.Sometimes people directly code in document.ready rather we can make meaningful function name and use that to code.
Comment on blocks of template (not lines) to specify the functions (only when necessary)
Use explanations of intent or clarification of code( in cases where the goals of the cord are not clear)
Use a warning of consequence (when changes in that cord will effect in several places)
New contributors will find it easy to make changes rather than struggling to find where to make the specific change.
Knowledge sharing process would happen more rapidly without needing the code owner to explain.
Time consuming and workload can be decreased drastically in the long term run .
Thought to make these suggestions since I was personally struggling in the last issue i was working on with where to make changes. And found out several contributors before me also faced the same issues in contributing.
Please make sure to give your ideas and add more into the approach section and rewards section to make it more productive.
Yeah that’s a good idea.
Also we can add instructions for navigating the repository or a project tree briefing the content of directories
Really appreciate your suggestions @Akeel_malik . Surely we can use your suggestion and create a backlog of tasks to improve developer experience.
Sure ill plan out and compose those as well , Thanks for the feedback @piumal1999
Yes I’ve talked with @anjisvj and @jaye as well , also we can even make several new issues regarding this and add the tag “good first issue” for people to work on them so on top of the readability even the people who will be working on these issues will gain knowledge regarding the features used in the repo’s. @YohanAvishke .
This is really awesome @Akeel_malik Having good documentation is always helpful for newcomers. Hope you can do this for other projects as well.
@anjisvj sure ill look into it with pleasure and make changes for all projects possible
Added a Prerequisites session for the README.md in the sef-site repo
added Node.js and npm in the description form of prerequisites session
We can get some inspiration from fossasia:
This has a readme file:
@jaye Thanks alot for the guidance ill sure look into it thoroughly and them implemented in our repo’s asap.
We can seperate a section in the README.md for pull requests. It gives a guide in best practices but not a step by step guide for a pull request. we can add some procedures to follow in sending PRs and also a guide to fill out the prebuilt PR session in the sef-site repo as @Gravewalker described in the knowledge share session.
Excellent idea, we already have them written in our developer guide. Maybe we can put that in a place more discoverable??
Exactly , that would be nice. Ill look into it . Thanks for the heads up. @Gravewalker
@Gravewalker @jaye @anjisvj @YohanAvishke @piumal1999
(A) Shall we drag the Commits/Pull Requests session in the CONTRIBUTING.md to README.md?
(B) Make a separate simplified pull request session to give a brief intro and link the CONTRIBUTING.md Commits/Pull Requests session for further details?
Which option is better . or is there anything better option than both of the above?
We can add a session to specify and guide people towards the software’s / features in our repo. (not prerequisites)
We have ,
being used in our sef-site repo . we can add a session as
1.this site is built using … or
or any other better idea for a topic you can come u with.