# Improve readability of our repository's codes **URL:** \ **Category:** Development\ **Created:** [July 16, 2021, 7:59am UTC](https://sef.discourse.group/t/improve-readability-of-our-repositorys-codes/333 "2021-07-16T07:59:04Z")\ **Posts on this page:** 17\ **Page:** 1
**Author:** ![Akeel\_malik](https://yyz2.discourse-cdn.com/free1/user_avatar/sef.discourse.group/akeel_malik/32/666_2.png) [@Akeel\_malik](https://sef.discourse.group/u/Akeel_malik)\ **Post date:** [July 16, 2021, 7:59am UTC](https://sef.discourse.group/t/improve-readability-of-our-repositorys-codes/333/1 "2021-07-16T07:59:05Z")
We can upgrade the readability of the codes in our repo’s by making some subtle yet important changes, **Goals** - 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.\*\* **Approach** 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. 1. Comment on blocks of template (not lines) to specify the functions (only when necessary) 2. Use explanations of intent or clarification of code( in cases where the goals of the cord are not clear) 3. Use a warning of consequence (when changes in that cord will effect in several places) **Reward** - 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. 🤓 ---
**Author:** ![piumal1999](https://yyz2.discourse-cdn.com/free1/user_avatar/sef.discourse.group/piumal1999/32/274_2.png) [@piumal1999](https://sef.discourse.group/u/piumal1999)\ **Post date:** [July 17, 2021, 10:17am UTC](https://sef.discourse.group/t/improve-readability-of-our-repositorys-codes/333/2 "2021-07-17T10:17:33Z")
Yeah that’s a good idea. > [@Akeel\_malik](#): > > 1.Specifying features or software’s used in files _ex: add in readme, mustache JS is used for these files._ Also we can add instructions for navigating the repository or a project tree briefing the content of directories ---
**Author:** ![YohanAvishke](https://yyz2.discourse-cdn.com/free1/user_avatar/sef.discourse.group/yohanavishke/32/106_2.png) [@YohanAvishke](https://sef.discourse.group/u/YohanAvishke)\ **Post date:** [July 17, 2021, 10:28am UTC](https://sef.discourse.group/t/improve-readability-of-our-repositorys-codes/333/3 "2021-07-17T10:28:58Z")
Really appreciate your suggestions @Akeel_malik . Surely we can use your suggestion and create a backlog of tasks to improve developer experience. ---
**Author:** ![Akeel\_malik](https://yyz2.discourse-cdn.com/free1/user_avatar/sef.discourse.group/akeel_malik/32/666_2.png) [@Akeel\_malik](https://sef.discourse.group/u/Akeel_malik)\ **Post date:** [July 17, 2021, 2:28pm UTC](https://sef.discourse.group/t/improve-readability-of-our-repositorys-codes/333/4 "2021-07-17T14:28:15Z")
Sure ill plan out and compose those as well , Thanks for the feedback @piumal1999 🤓 ---
**Author:** ![Akeel\_malik](https://yyz2.discourse-cdn.com/free1/user_avatar/sef.discourse.group/akeel_malik/32/666_2.png) [@Akeel\_malik](https://sef.discourse.group/u/Akeel_malik)\ **Post date:** [July 17, 2021, 2:31pm UTC](https://sef.discourse.group/t/improve-readability-of-our-repositorys-codes/333/5 "2021-07-17T14:31:42Z")
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 . ---
**Author:** ![anjisvj](https://yyz2.discourse-cdn.com/free1/user_avatar/sef.discourse.group/anjisvj/32/9_2.png) [@anjisvj](https://sef.discourse.group/u/anjisvj)\ **Post date:** [July 17, 2021, 2:43pm UTC](https://sef.discourse.group/t/improve-readability-of-our-repositorys-codes/333/6 "2021-07-17T14:43:55Z")
This is really awesome 😍 @Akeel_malik Having good documentation is always helpful for newcomers. Hope you can do this for other projects as well. 😋 ---
**Author:** ![Akeel\_malik](https://yyz2.discourse-cdn.com/free1/user_avatar/sef.discourse.group/akeel_malik/32/666_2.png) [@Akeel\_malik](https://sef.discourse.group/u/Akeel_malik)\ **Post date:** [July 17, 2021, 3:30pm UTC](https://sef.discourse.group/t/improve-readability-of-our-repositorys-codes/333/7 "2021-07-17T15:30:10Z")
@anjisvj sure ill look into it with pleasure and make changes for all projects possible 👍 ---
**Author:** ![Akeel\_malik](https://yyz2.discourse-cdn.com/free1/user_avatar/sef.discourse.group/akeel_malik/32/666_2.png) [@Akeel\_malik](https://sef.discourse.group/u/Akeel_malik)\ **Post date:** [July 17, 2021, 4:01pm UTC](https://sef.discourse.group/t/improve-readability-of-our-repositorys-codes/333/8 "2021-07-17T16:01:32Z")
[https://github.com/sef-global/sef-site/pull/1030](https://github.com/sef-global/sef-site/pull/1030) Added a Prerequisites session for the README.md in the sef-site repo ---
**Author:** ![Akeel\_malik](https://yyz2.discourse-cdn.com/free1/user_avatar/sef.discourse.group/akeel_malik/32/666_2.png) [@Akeel\_malik](https://sef.discourse.group/u/Akeel_malik)\ **Post date:** [July 18, 2021, 5:40am UTC](https://sef.discourse.group/t/improve-readability-of-our-repositorys-codes/333/9 "2021-07-18T05:40:52Z")
added Node.js and npm in the description form of prerequisites session ---
**Author:** ![jaye](https://yyz2.discourse-cdn.com/free1/user_avatar/sef.discourse.group/jaye/32/810_2.png) [@jaye](https://sef.discourse.group/u/jaye)\ **Post date:** [July 18, 2021, 5:44am UTC](https://sef.discourse.group/t/improve-readability-of-our-repositorys-codes/333/10 "2021-07-18T05:44:08Z")
We can get some inspiration from fossasia: This has a readme file: > **[fossasia/open-event-frontend](https://github.com/fossasia/open-event-frontend)** > > The frontend for the Open Event API Server. Contribute to fossasia/open-event-frontend development by creating an account on GitHub. ---
**Author:** ![Akeel\_malik](https://yyz2.discourse-cdn.com/free1/user_avatar/sef.discourse.group/akeel_malik/32/666_2.png) [@Akeel\_malik](https://sef.discourse.group/u/Akeel_malik)\ **Post date:** [July 18, 2021, 5:53am UTC](https://sef.discourse.group/t/improve-readability-of-our-repositorys-codes/333/11 "2021-07-18T05:53:02Z")
@jaye Thanks alot for the guidance ill sure look into it thoroughly and them implemented in our repo’s asap. 🤓 ---
**Author:** ![Akeel\_malik](https://yyz2.discourse-cdn.com/free1/user_avatar/sef.discourse.group/akeel_malik/32/666_2.png) [@Akeel\_malik](https://sef.discourse.group/u/Akeel_malik)\ **Post date:** [July 22, 2021, 7:59am UTC](https://sef.discourse.group/t/improve-readability-of-our-repositorys-codes/333/12 "2021-07-22T07:59:52Z")
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. ---
**Author:** ![Gravewalker](https://yyz2.discourse-cdn.com/free1/user_avatar/sef.discourse.group/gravewalker/32/12_2.png) [@Gravewalker](https://sef.discourse.group/u/Gravewalker)\ **Post date:** [July 22, 2021, 8:42am UTC](https://sef.discourse.group/t/improve-readability-of-our-repositorys-codes/333/13 "2021-07-22T08:42:35Z")
Excellent idea, we already have them written in our developer guide. Maybe we can put that in a place more discoverable?? ---
**Author:** ![Akeel\_malik](https://yyz2.discourse-cdn.com/free1/user_avatar/sef.discourse.group/akeel_malik/32/666_2.png) [@Akeel\_malik](https://sef.discourse.group/u/Akeel_malik)\ **Post date:** [July 22, 2021, 12:20pm UTC](https://sef.discourse.group/t/improve-readability-of-our-repositorys-codes/333/14 "2021-07-22T12:20:17Z")
Exactly , that would be nice. Ill look into it . Thanks for the heads up. @Gravewalker ---
**Author:** ![Akeel\_malik](https://yyz2.discourse-cdn.com/free1/user_avatar/sef.discourse.group/akeel_malik/32/666_2.png) [@Akeel\_malik](https://sef.discourse.group/u/Akeel_malik)\ **Post date:** [July 22, 2021, 4:56pm UTC](https://sef.discourse.group/t/improve-readability-of-our-repositorys-codes/333/15 "2021-07-22T16:56:15Z")
@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? ---
**Author:** ![Akeel\_malik](https://yyz2.discourse-cdn.com/free1/user_avatar/sef.discourse.group/akeel_malik/32/666_2.png) [@Akeel\_malik](https://sef.discourse.group/u/Akeel_malik)\ **Post date:** [July 23, 2021, 1:40pm UTC](https://sef.discourse.group/t/improve-readability-of-our-repositorys-codes/333/16 "2021-07-23T13:40:01Z")
We can add a session to specify and guide people towards the software’s / features in our repo. (not prerequisites) We have , 1.Bootstrap 2.JQuery 3 MaustacheJs being used in our sef-site repo . we can add a session as 1.this site is built using … or 2.further reading or any other better idea for a topic you can come u with. ---
**Author:** ![Akeel\_malik](https://yyz2.discourse-cdn.com/free1/user_avatar/sef.discourse.group/akeel_malik/32/666_2.png) [@Akeel\_malik](https://sef.discourse.group/u/Akeel_malik)\ **Post date:** [July 29, 2021, 3:55am UTC](https://sef.discourse.group/t/improve-readability-of-our-repositorys-codes/333/17 "2021-07-29T03:55:11Z")
Adding Documentation links to prerequisites and tech stack sessions in README.md [Add a Tech stack session to README.md by akeel230 · Pull Request #1055 · sef-global/sef-site (github.com)](https://github.com/sef-global/sef-site/pull/1055) [Add documentation to prerequisites session in README.md by akeel230 · Pull Request #1058 · sef-global/sef-site (github.com)](https://github.com/sef-global/sef-site/pull/1058)