Write a more standard README file

[miquelduranfrigola]

We want to write a better README file, including better installation instructions and a better description of the package features. Are there any guidelines to a good README file?

[AnshuKumari197]

@GemmaTuron @miquelduranfrigola Yes, I have guidelines for a good README file. If you allow me then I will write a better README file for this organization. Please assign me this work.

[Melkeb]

Yes, there are some guidelines for writing a README and these are some of the relevant guidelines I have found.

Links
https://www.welcometothejungle.com/en/articles/btc-readme-documentation-best-practices
https://www.freecodecamp.org/news/how-to-write-a-good-readme-file/
https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/
https://github.com/elsewhencode/project-guidelines/blob/master/README.sample.md
https://loopback.io/doc/en/contrib/README-guidelines.html
https://dev.to/siddharthshyniben/how-to-write-a-good-readme-cn0
https://coding-boot-camp.github.io/full-stack/github/professional-readme-guide
https://www.makeareadme.com/

Relevant Scholar Articles
https://www.jstage.jst.go.jp/article/transinf/E102.D/2/E102.D_2018EDP7071/_pdf
https://arxiv.org/pdf/1802.06997.pdf
https://pure.knaw.nl/ws/portalfiles/portal/2431218/softwareguidelines_1_.pdf (Page 7)

General Guideline for a better documentation book

Read Me First!: A Style Guide for the Computer Industry
https://books.google.com.et/books?hl=en&lr=&id=TJSwqVS24CYC&oi=fnd&pg=PR19&dq=guideline+for+writing+a+readme+file&ots=2CPP6_xvHY&sig=qmLwaOIhAntuqlyO5LPNwd9tFzo&redir_esc=y#v=onepage&q=guideline%20for%20writing%20a%20readme%20file&f=false

About: A reference for technical writers, editors, and documentation managers working on documenting hardware, software, and other computer products. Offers grammar and punctuation guidelines, typographic conventions, and advice of creating bibliographies and indexes.

Happy to help out in any way I can.

[Kcfreshly]

I hope this sample page and guideline for a better doumentation will be helpful..

An interesting sample of a readme

https://github.com/ohmyzsh/ohmyzsh

A great Template for readme

https://www.drupal.org/docs/develop/managing-a-drupalorg-theme-module-or-distribution-project/documenting-your-project/readme-template

I can also create a more engaging and easy to understand writing for the Readme file.

I worked on the first paragraph in our readme,

"The Ersilia Model Hub is a patient zero of Ersillia Open Source Initiative. The platform will deploy user-friendly AI/models. This will enable scientists with no coding expertise to use these models easily and also identity key models needed in their research. The information obtained from the AI/Model will help scientists predict and develop better approaches to health challenges."

[busiratbolanle]

Here is a Sample ReadME Guide that I came up with after doing some research on ReadME file
For easy understanding, I checked the part of the guide that the current ReadMe file has been able to justify.

• Project title
• Project description
• Table of contents
• Technologies
• Features
• Screenshots
• Installation instruction
• Operation
• Project stage
• Future development
• Acknowledgements
• Contact

The installation instructions should include some image as guide for better user experience.
With this guidelines, we can create a much better ReadME file.

[Kcfreshly]

Here is a Sample ReadME Guide that I came up with after doing some research on ReadME file For easy understanding, I checked the part of the guide that the current ReadMe file has been able to justify.

• Project title
• Project description
• Table of contents
• Technologies
• Features
• Screenshots
• Installation instruction
• Operation
• Project stage
• Future development
• Acknowledgements
• Contact

The installation instructions should include some image as guide for better user experience. With this guidelines, we can create a much better ReadME file.

Honestly your points are so valid, however, I made a little tweak to your checklist.

[Elizabeth-Joseph-Mawutin]

I found this guideline useful for writing a good ReadMe file.

https://www.freecodecamp.org/news/how-to-write-a-good-readme-file/
https://www.makeareadme.com/

I believe a good ReadMe file should have these

• Project title
• Project Description
• Table of contents
• Project installation
• Usage
• Acknowledgment
• License

[harshita214]

@miquelduranfrigola @GemmaTuron I am interested to contribute to this issue, by keeping in mind the points highlighted by @ashaby4000 @Kcfreshly @ElizabethMawutin, I am willing to work collaboratively also with them.

[GemmaTuron]

Hello,

Thanks for your interest! Here some comments and how to continue working on this:
@ashaby4000 the checklist is a good idea to work from there, thanks for sharing that
@Kcfreshly please revise what is the Ersilia Model Hub and your first line: The Ersilia Model Hub is a patient zero of Ersillia Open Source Initiative. The platform will deploy user-friendly AI/models. Make sure this makes sense.

@ashaby4000, @Kcfreshly, @AnshuKumari197 and @harshita214 and @ElizabethMawutin we would love you to give it a go at improving the readme file! To avoid versioning issues, please create and upload an md file with the name <README_yourname.md> in the /documentation (not /docs) folder.
Take as much time as needed, the next weeks we will work on merging these readme in a final one if you are interested.

For next applicants, this issue will accept 10 contributions, it currently is assigned to 5. Ping me if you wish to work in this as well.

[arushi2715]

Hello @GemmaTuron I want to work on this.

[martwebber]

Hello @GemmaTuron, I would love to contribute to this issue.

[pauline-banye]

Hi @GemmaTuron, I would love to contribute to this issue. I have reviewed the suggestions presented by @Kcfreshly, @Ashaby4000, @ElizabethMawutin, @harshita214 and @AnshuKumari197 and I believe I can collaborate effectively with them to improve the readme.

[ugo-bee]

Hi @GemmaTuron i would love to contribute to this issue

[adeola-dev]

Hi @GemmaTuron , I would love to contribute to this issue.

[Shivani-Parihar99]

Hi @GemmaTuron , I would love to contribute to this issue as well.

[GemmaTuron]

Hello @martwebber, @pauline-banye, @arushi2715, @Melkeb and @ugo-bee

I have assigned this task to you as well.

@adeola-dev and @Shivani-Parihar99 , thanks for your interest, please give the assignes a few days to work on this and next week we will continue the work on README files and you will have more opportunities for contributing

[Shivani-Parihar99]

@GemmaTuron Thankyou for consideration.

[pauline-banye]

Thank you @GemmaTuron, I can't wait to get started.

[martwebber]

Thank you @GemmaTuron

[srcmilena]

hello @GemmaTuron

i would love to contribute to this issue

[Emidowojo]

Hello, @GemmaTuron can I contribute to this issue?

[pauline-banye]

Hello @GemmaTuron , I have worked on the readme but I've encountered issues creating a separate documentation folder due to the fact that there is currently a file name documentation. Do I rename the file? It is currently blank.

[GemmaTuron]

Hello @GemmaTuron , I have worked on the readme but I've encountered issues creating a separate documentation folder due to the fact that there is currently a file name documentation. Do I rename the file? It is currently blank.

Hi @pauline-banye the issue should be solved now so you can try to add your readme file in the /documentation folder. Please add your name so I know who has created it!

[GemmaTuron]

@Emidowojo @srcmilena Please read issue #49

This issue is initially assigned to 10 participants. We are thinking of the best way to open it to more contributors, give us a few days to think through it.

[SHRIYA1706]

Hi @GemmaTuron, I would like to contribute to this issue by adding some visual effects with HTML code to make a eye-catching README. Please assign this issue to me.

[loweyvana]

Hi @GemmaTuron , please I would love to make some contributions to this project in collaboration with the other assignees. Would that be possible please?

[loweyvana]

Going through the project description, found the purpose of Ersilia is to enable scientists ( mostly in LMIC) WITHOUT CODING EXPERTISE to have to more access to AI which they can use to obtain predictions. However, going through the installation process is a little bit complex and contains many technical words which might be difficult to understand for someone not in a field. Here are some suggestions i think can help with the installation process;
-keep the language very simple and straightforward.

• Add a demo screenshot of the expected outputs at each stage of the installation process.
  -Make the whole process more visual by including demo screenshots, or better still, GIF demos. If I am assigned, I'd use tools such as https://github.com/icholy/ttygif to convert terminal recordings to animated gifs, OR https://asciinema.org/ to record and share terminal sessions of the installation process. NB: https://asciinema.org/ supprts Linux and macOS.
• Furthermore, i think it'd be awesome if we could add a support section on the table of contents where people can go to for help. It could be a chat room; an email adress etc

[pauline-banye]

Hello @GemmaTuron , I have worked on the readme but I've encountered issues creating a separate documentation folder due to the fact that there is currently a file name documentation. Do I rename the file? It is currently blank.

Hi @pauline-banye the issue should be solved now so you can try to add your readme file in the /documentation folder. Please add your name so I know who has created it!

Thanks @GemmaTuron 😀. Would update my repo and make a PR.

[Ye7ni]

Hello @GemmaTuron I've gone through the guidelines listed on this page as well as done my research on how to create a most compelling READ ME. Pls assign me to this project to contribute my bit. Thanks

[loweyvana]

Here is a great link for awesome READMEs
There is no one-format-fits-all because every project is different. However, here is a great guide which can be adjusted to best fit with Ersilia. I am willing , ready and available to contribute to this.

https://github.com/matiassingers/awesome-readme

[resiato]

Hello @GemmaTuron I am interested in this project. I have gone through the https://www.freecodecamp.org/news/how-to-write-a-good-readme-file/ guideline and it offers the best steps in formulating a standard README.md file

[miquelduranfrigola]

Hi All! This is a fantastic thread here. I am closing the issue for now, since we already got a lot of great feedback from many people. Might reopen in the future. Thanks to all of you for your contributions!

[JyteCeo]

@Emidowojo @srcmilena Please read issue #49

This issue is initially assigned to 10 participants. We are thinking of the best way to open it to more contributors, give us a few days to think through it.

@GemmaTuron is this now open for other applicants to contribute to it .. ?

[srcmilena]

@JyteCeo hello! i read the issue. could you explain to me how can i help/join?