Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update the Examples Readme #312

Open
shaistha24 opened this issue Oct 20, 2020 · 23 comments
Open

Update the Examples Readme #312

shaistha24 opened this issue Oct 20, 2020 · 23 comments
Labels
Good first issue 🎓 Perfect for beginners, welcome to OpenMined! Hacktoberfest Open for hacktoberfest 2020 Status: Available 👋 Available for assignment, who wants it?

Comments

@shaistha24
Copy link
Contributor

Where?

https://github.com/OpenMined/PyDP/tree/dev/examples

Who?

Anyone looking for PyDP examples/demo

What?

Example/demo sub-title with short description and link.
@shaistha24 shaistha24 added the Type: Documentation 📚 Improvements or additions in documentation for some file, feature, or codebase label Oct 20, 2020
@chinmayshah99 chinmayshah99 added Good first issue 🎓 Perfect for beginners, welcome to OpenMined! Hacktoberfest Open for hacktoberfest 2020 Status: Available 👋 Available for assignment, who wants it? and removed Type: Documentation 📚 Improvements or additions in documentation for some file, feature, or codebase labels Oct 20, 2020
@LiviaCavalcanti
Copy link

Hi! Sorry, I didn't understand what is to be done. Do new examples have to be added?

@shaistha24
Copy link
Contributor Author

@LiviaCavalcanti if you check it the readme is pretty much outdated. Need to update it with all the examples/demos that have been added, with a little description for the viewer to know which example/demo does what.

Hope this answers your question.

@chinmayshah99
Copy link
Member

Hi @LiviaCavalcanti
Adding to Shaishta's comment, if you visit Readme in examples, you will find that it only houses 1 demo, even though we have 3 demos, so we are looking to add a description of these demos in the readme.

@AkashM398
Copy link

Is anyone working on this? I would like to take over.

@chinmayshah99
Copy link
Member

Hey @LiviaCavalcanti are you taking this up?

@LiviaCavalcanti
Copy link

No, no @chinmayshah99. Feel free to work on it, @AkashM398

@chinmayshah99
Copy link
Member

@AkashM398 assigning it to you.

@Rajatendu1
Copy link

Hey @chinmayshah99 @shaistha24 , I would like to work on this issue.

@Rajatendu1
Copy link

Hi @chinmayshah99 I would like to take up this issue since @AkashM398 is inactive for quite a while as per our conversation in slack.

@chinmayshah99
Copy link
Member

chinmayshah99 commented Oct 30, 2020 via email

@Rajatendu1
Copy link

Rajatendu1 commented Oct 30, 2020 •
edited
Loading

I have added the examples in the main project README.md as well as added the description in the respective folders of the examples. Have a look and notify me of any changes if needed. @chinmayshah99

@8bitmp3
Copy link
Contributor

8bitmp3 commented Oct 30, 2020

PTAL @Rajatendu1 #320 (comment) Thanks!

@8bitmp3
Copy link
Contributor

8bitmp3 commented Oct 30, 2020

https://x-team.com/blog/how-to-write-a-great-readme/ - "How to write a great README" - it may be helpful

What to Include in Your README

Here are some of the essential things to include when you're writing your README. We'll assume that you're familiar with markdown to organize your file and make it look good.

  • Title (can be text or an image)
  • Introduction (what it's about & why you wrote it)
  • How to install
  • How to use
  • Technologies used (libraries & versions, helps recruiters)
  • Acknowledgments

Those are the absolute essentials. They make for a good README. If you want to write a great one, you can take it a step further and include:

  • Table of contents (useful if your README is long)
  • List of features
  • Examples of use (with code or images)

@8bitmp3
Copy link
Contributor

8bitmp3 commented Oct 30, 2020

I'd also recommend the Google style doc that many folks use to write better READMEs and docs: https://developers.google.com/style (formatting, style, language, grammar)

@8bitmp3
Copy link
Contributor

8bitmp3 commented Oct 30, 2020

Hi @Rajatendu1 @shaistha24 @chinmayshah99 Would it be good to use something like jupytext to convert the notebook(s) into Markdown and then include the most important bits in the READMEs?

Currently, like in the Laplace demo README PR - https://github.com/OpenMined/PyDP/pull/318/files - there are mentions of different sections of the notebook without examples which may make it hard to follow, I think.

And, if some of the introductory work has been done in the notebook, it can be ported over into a README to improve the process of making "better READMEs" (as per https://x-team.com/blog/how-to-write-a-great-readme/):

  • Title (can be text or an image)
  • Introduction (what it's about & why you wrote it)
  • How to install
  • How to use
  • Technologies used (libraries & versions, helps recruiters)
  • Acknowledgments

As mentioned before, the Google style doc is great for writing better READMEs and docs: https://developers.google.com/style (formatting, style, language, grammar). Check out the Microsoft style too - https://docs.microsoft.com/en-us/style-guide/welcome/ 👍

In addition, I'd recommend running the text through a free grammar checker (Google Docs them) before submitting any PRs.

@shaistha24
Copy link
Contributor Author

the template to follow for readme is this in general for the main readme is this https://github.com/OpenMined/.github/blob/master/README-TEMPLATE.md just in case.

@8bitmp3 Yes, what you have listed definitey makes sense and is easy to follow for the viewers.

Jupytext seems like a good idea to scrape the Notebook for the info we want to put on the README with less efforts and faster results.

I myself follow Google style docs most of the times. And would highly recommend that to all. As for the Grammar check, Grammarly kinda works best for me.

@zihangxiang
Copy link

Is completing the "Good First Issue" necessary to get involved in the GSoC 2021, if yes, I'd like to be assigned with this open issue.

@chinmayshah99
Copy link
Member

sure, you can take this up.

@dnabanita7
Copy link
Contributor

Is it available?

@chinmayshah99
Copy link
Member

chinmayshah99 commented Apr 8, 2021 via email

This was referenced Apr 9, 2021
Closed
Merged
@SauravMaheshkar
Copy link
Contributor

I'd like to work on this Issue. To be the specific the laplace_demo could do with some love ❤️, for instance, some LaTeX in the Notebook is broken and it doesn't have a README in the first place.

CC: @shaistha24 / @chinmayshah99 (Sorry for the @ 😅)

@chinmayshah99
Copy link
Member

Sure, you can take this up @SauravMaheshkar.

@SauravMaheshkar SauravMaheshkar mentioned this issue Dec 14, 2021
Merged
4 tasks
@chinmayshah99
Copy link
Member

chinmayshah99 commented Dec 19, 2021 via email

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Good first issue 🎓 Perfect for beginners, welcome to OpenMined! Hacktoberfest Open for hacktoberfest 2020 Status: Available 👋 Available for assignment, who wants it?
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
9 participants
@chinmayshah99 @8bitmp3 @LiviaCavalcanti @shaistha24 @Rajatendu1 @dnabanita7 @AkashM398 @SauravMaheshkar @zihangxiang