search

WattTime / pyiso

Python client libraries for ISO and other power grid data sources.
http://pyiso.readthedocs.org/
Other
239 stars 112 forks source link

Overhaul the pyiso README #172

Closed r24mille closed 2 years ago

r24mille commented 6 years ago

Currently, pyiso's README could be summed up as containing the following content:

  1. relevant badges giving newcomers a glance at the project's overall state of health.
  2. a two-sentence description of what the project is for.
  3. a link to the full documentation on Read The Docs.
  4. a link back to the guiding organization, WattTime.
  5. a changelog.

The first four items are a good start, but could use some improvement. For item five, the changelog, I'd be more inclined to look at https://github.com/WattTime/pyiso/releases.

All that said, I think pyiso's README could use a hug. While doing some background reading on the topic, many site point to https://open-source-guide.18f.gov/making-readmes-readable/ as a good point of reference. I agree, that if we follow the guidance in that article, our README would be much improved. Also notable is someone's list of exemplar project README documents, https://github.com/matiassingers/awesome-readme.

To fix this issue, I think the following changes should be made:

  1. Modify release information in each release listed in https://github.com/WattTime/pyiso/releases to contain the current Change Log contents OR Break the changelog out into its own CHANGELOG.md file.
  2. Modify our README content to conform to the guidance provided in https://open-source-guide.18f.gov/making-readmes-readable/ to maximize its utility.
  3. Look over some examples from https://github.com/matiassingers/awesome-readme and make some final modifications so that it draws new contributors in (i.e. a picture is worth a thousand words and logos give a sense of legitimacy).