Add: readme file tutorial to packaging 101 series

[lwasser]

This PR adds a new tutorial on creating a readme file. The following tutorials will be:

1. add a license and code of conduct and then
2. add a pyproject.toml file
   The current break in CI relates to the next lesson (links to it) that aren't in this PR but the lesson draft is done.

---

• To see the specific tasks where the Asana app for GitHub is being used, see below:
  • https://app.asana.com/0/0/1206433371892147

[kierisi]

added my notes!

[kierisi]

it might be helpful to link to example READMEs that we think are good exemplars (perhaps from some of our accepted packages and//or community partners?).

[lwasser]

agreed! hopefully once our example package is fleshed out we will have that one. but i love the idea of using others. maybe we can get folks in slack to provide examples that they think are good and following the criteria (generally) here? the one challenge is i tried to simplify this and so the sections are not necessarily required to be in this order with this content. so it might be tough to find examples that also map to our lesson unless we create it.

let's chat more!

[ucodery]

Another great tutorial!

[ucodery]

I personally think the biggest job of a README is to describe what the project does, maybe with a bit of a sales pitch, but at least a sort of problem statement. This is actually one of the required items for pyOS reviews so surprised it's not here.

[lwasser]

hey @ucodery this is great feedback. Step three below the badges is to add a description of the package and what it does. Are you looking for more detail here in terms of the "pitch" and need? OR are you looking for something more specific higher up? i added two screenshots below with content that i think addresses what you are looking for. but i suspect i'm missing something and may just need a bit of direction regarding what you think would make things better! many thanks. this feedback is super useful i just need guidance in implementing a fix!

[ucodery]

Hmmm, I think I may not be reading "what it does" in the way that you mean it.
I read that as just a prose description of what is inside. Maybe even just some docstrings. While I believe a better statement in the readme is why you should use it - the elevator pitch.

Just as a reminder, this is a required item for PyOS review:

A statement of need clearly stating problems the software is designed to solve and its target audience in README.

Which I think is great. To me, a "statement of need" reads differently than "what it does"

BUT this is really getting into tone and preferred writing style, and probably far off track for this PR. I don't think any changes are needed at this time. If I actually come up with a better tutorial phrasing, I can always propose new changes after this goes live :)

[lwasser]

ok no problem! i hear you.

i've added this to the bulleted list!

• You package's name
• What the package does. Your README file should clearly state the problem(s) that your software is designed to solve and its target audience.
• The current development "state" of the package (through badges)
• How to get started with using your package.
• How to contribute to your package
• How to cite your package

[lwasser]

and then yes you can also submit another pr to adjust language :) i'll try to merge this today given it's been open for a while!! 🚀

[lwasser]

thank you for the clarification and additional edits @ucodery 🚀 !! i'll look more closely at these tomorrow and merge then to ensure i can incorporate all of the feedback!!