Write a more standard README file about ersilia HOT 33 CLOSED

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.

from ersilia.

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."

from ersilia.

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.

from ersilia.

@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.

from ersilia.

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.

from ersilia.

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

from ersilia.

@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.

from ersilia.

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.

from ersilia.

Hello @GemmaTuron I want to work on this.

from ersilia.

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

from ersilia.

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.

from ersilia.

Hi @GemmaTuron i would love to contribute to this issue

from ersilia.

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

from ersilia.

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

from ersilia.

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

from ersilia.

@GemmaTuron Thankyou for consideration.

from ersilia.

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

from ersilia.

Thank you @GemmaTuron

from ersilia.

hello @GemmaTuron

i would love to contribute to this issue

from ersilia.

Hello, @GemmaTuron can I contribute to this issue?

from ersilia.

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.

from ersilia.

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!

from ersilia.

@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.

from ersilia.

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.

from ersilia.

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

from ersilia.

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

from ersilia.

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.

from ersilia.

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

from ersilia.

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

from ersilia.

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

from ersilia.

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!

from ersilia.

@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 .. ?

from ersilia.

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

from ersilia.