-
Notifications
You must be signed in to change notification settings - Fork 264
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.
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
Add a little Pizzaz to the Readme #1047
Comments
Yep - sounds good. We should have installation and usage stuff in the docs. The readme can then be a 'sales pitch' |
I also reckon the initial paragraph ("Currently ...") is a bit heavy, by the time I get to the |
We should have a very minimum of installation stuff still:
and
(or |
Might I humbly suggest something more like this repository? |
There is a lot in that README. Do you have separate documentation elsewhere
for that or is that your user documentation also?
It might just be the nature of ~~tertiary~~ternary but I'd be cautious about overlap
with our docunentation (our README is not our user documentation). I like
@meatballs way of phrasing it: a sales pitch.
I'd suggest the audience of the README is either developers who will want
to be pointed at our contribution documentation (without having to read a
lot). Or potential users who'll want that sales pitch and a pointer to the
documentation.
To add to the examples here's my README for Nashpy
https://github.com/drvinceknight/Nashpy
…On Sun, 18 Jun 2017, 20:31 Marc Harper, ***@***.***> wrote:
Might I humbly suggest something more like this repository
<https://github.com/marcharper/python-ternary>?
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#1047 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/ACCGWipzancu8ldJqg9yl6HUb2tyS0Wiks5sFXsRgaJpZM4N9jm8>
.
|
And here's another example: https://github.com/PyconUK/ConferenceScheduler |
I wouldn't be surprised if we're actually all on the same page and it might be helpful for someone to just take a stab at this to give us a reference point... |
For further reference (I'm not suggesting that any of these are what we want for Axelrod, just throwing things out here):
|
I'd suggest that's a way to go:
Crap. Sorry, I think I'm now actually suggesting the opposite of adding pizzaz... 😭 |
My repository readme is all the documentation, I'm not suggesting we do that. But it has some nice plots, some easy "get started" examples, some visuals of what the library can do, etc. Once people are hooked on that, then the drudgery of how to install and such can follow. When I go to a readme for a project I don't know about, how to install it is not what I care about. It's do I want to install this? Does it do what I need it to? |
You're right. The README should be an overview of what the library can do. My preference would be that it is very brief though, so not only should the README tell me if I want to install this but also if I want to invest more time reading about what this is. So I'd suggest no plots, no visuals, just a bullet point list at the start with the things it can do. We could/should of course link to where those plots/visuals can be found though. So something like: # Axelrod
Axelrod
=======
A Python library with the following principles and goals:
1. Enabling the reproduction of previous Iterated Prisoner's Dilemma research
as easily as possible.
2. Creating the de-facto tool for future Iterated Prisoner's Dilemma
research.
3. Providing as simple a means as possible for anyone to define and contribute
new and original Iterated Prisoner's Dilemma strategies.
4. Emphasizing readability along with an open and welcoming community that
is accommodating for developers and researchers of a variety of skill levels.
**The library has a growing list of more than 200 strategies.** These include classic strategies from the literature and original strategies. (link to strategies list)
With Axelrod you can:
- Create head to head matches between any two strategies. Examples:
- link to docs on matches
- Efficiently create tournaments of various types between any number of strategies. Examples:
- link to docs on tournaments
- link to tournament repo
- Study Moran Processes. Examples:
- link to (various) docs on Moran processes
- Analyse detailed results of tournaments and matches
- link docs on result sets
- link to tournament repo (the summary data)
- link to the examples notebook repo
- Visualise results of tournaments. Examples
- link to plot docs
- link to tournament repo
- link to the examples notebook repo
- Reproduce a number of research results
- Fingerprinting of strategies:
- Link to docs on fingerprinting
- Link to fingerprinting repo
- Morality metrics (link to section of docs on Morality metrics)
For a detailed overview of the capabilities of the library see the extensive documentation: link to documentation. Following that we can have (very) short sections about:
I think I'm in preference of a sales pitch in elevator pitch form:
FWIW, we used to have more graphics in the README (a small tournament as well as the bigger tournament and possibly more if I recall correctly) and we decided to clear that out (which I think was a good way to go) in the interest of streamlining and deduping what might be in the documentation. We already have a lot of examples in a number of places, we should use them. |
Recall that we do have a similar such list at the start of the documentation: http://axelrod.readthedocs.io/en/stable/ Depending on what we do with the README we should remember to potentially change that. |
Here's an SO discussion about writing README's: https://stackoverflow.com/questions/2304863/how-to-write-a-good-readme |
I am looking forward to a good re-write of the read me. If you don't mind me commenting. I like the idea of pointing out what you can do with the library but more as a little sections that also For example: FingerprintingAllow you to this. I agree with Marc that this is a good sale point and the library does provide several impressive graphs. Add links to all the example that have been written and not used, but after a taste of what they actually look like.
But yes it's tricky as to when you start repeating the same things. |
It sounds like this is the main point where we don't agree, I'd suggest we don't include plots and keep things VERY brief (no code snippets, just elevator pitches). Fwiw, that's also what's suggested by the top answer in that SO link (although I'm keen to stress that just because "someone on the internet has said it, it doesn't mean it's right"). |
Based on conversation at #1047.
Two suggestions to give us a relative discussion point:
The way I've thrown the plots in that second one isn't great as they're given no context, but I think that's why I'd rather not have any graphics, for them to have context we need to add more explanation (code perhaps) and weigh down the README. |
Counterexample: seaborn, which leads with some nice plots. It's a plotting library so it's sort of expected... nevertheless I have some idea what the library will do for me before I've really read any words. I think maybe three plots: a tournament, a heatmap, and a fingerprint, perhaps. I also recommend a few lines for running a match + sparklines. |
That's a good counterpoint to why I'm hesitant right? A good balance of images presented it the right way would help with the "elevator pitch" I'm trying to edge towards. I'm just keen to make the README brief/efficient.
Cool, I'm not averse to that, @marcharper do you want to perhaps take a stab on top of that |
Feel free not to of course, if you think that's setting off in the wrong direction to begin with :) |
I suspect what we're wrestling with here is that there are, broadly, at least two very different types of user who might stumble across the library and we want to be 'wowed' by the README:
|
I'll give it a go. |
Personally I've always thought of seaborn's documentation as some of the worse I've seen (for something that has a lot of documentation) but I like the README: still short, brief and sharp. 👍 |
Based on conversation at #1047.
#1072 refactored the README. Closing but reopen if it's not felt that's sufficient. |
@marcharper can you clarify what you still want done for this? |
I'll open a PR or close the bug if I'm happy soon |
👍 |
Some suggestions:
Thoughts @drvinceknight @meatballs ?
The text was updated successfully, but these errors were encountered: