Add a little Pizzaz to the Readme

[marcharper]

Some suggestions:

• Image of a small tournament (see examples repo)
• Sparklines of a match
• A plot of the Moran process like the one in this notebook
• A cooperation heatmap from the examples repository
• A couple of fingerprints
• Remove some of the installation instructions (like mpl issues on ubuntu) -- could go into a wiki page
• Make the reference paper more prominent

Thoughts @drvinceknight @meatballs ?

[meatballs]

Yep - sounds good. We should have installation and usage stuff in the docs. The readme can then be a 'sales pitch'

[drvinceknight]

I also reckon the initial paragraph ("Currently ...") is a bit heavy, by the time I get to the README I'd like short and sharp information/sale pitches. If I want details I'll look at the documentation.

[drvinceknight]

We should have a very minimum of installation stuff still:

pip install axelrod

and

python setup.py develop

(or install) basically what we have there now without the issues about ubuntu. :) 👍

[marcharper]

Might I humbly suggest something more like this repository?

[drvinceknight]

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

[drvinceknight]

And here's another example: https://github.com/PyconUK/ConferenceScheduler

[drvinceknight]

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

[drvinceknight]

For further reference (I'm not suggesting that any of these are what we want for Axelrod, just throwing things out here):

• https://github.com/numpy/numpy is extremely short and just has a few bullet points.
• https://github.com/scipy/scipy#documentation also pretty bare but points to all relevant links.

[drvinceknight]

• https://github.com/pandas-dev/pandas is a brief overview of what it can do (bullet points) followed by pointers.

I'd suggest that's a way to go:

• Clean up the currently heavy initial paragraphs, replace them with bullet points (of what the library can do, similar to pandas, conference scheduler etc): brief sentences for Matches, Tournaments, Moran processes, fingerprints etc...
• Point at the documentation
• Dependencies (py3 only...)
• Installation instructions
• Installation from source instructions
• Point at the other repos/projects (tournament, fingerprints, etc)
• Remove everything else

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

Crap. Sorry, I think I'm now actually suggesting the opposite of adding pizzaz... 😭

[marcharper]

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?

[drvinceknight]

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:

• The paper
• Dependencies/Installation;
• Contributing (link to contributing);
• etc...

I think I'm in preference of a sales pitch in elevator pitch form:

• If you want to know a list of what the library can do: README
• If you want to know how to do it and what it looks like: documentation.

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.

[drvinceknight]

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.

[drvinceknight]

Here's an SO discussion about writing README's: https://stackoverflow.com/questions/2304863/how-to-write-a-good-readme

[Nikoleta-v3]

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
includes plots/graphs, as Marc suggested.

For example:

Fingerprinting

Allow you to this.
scroll
Images one, Image two.

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.

We already have a lot of examples in a number of places, we should use them.

But yes it's tricky as to when you start repeating the same things.

[drvinceknight]

I like the idea of pointing out what you can do with the library but more as a little sections that also
includes plots/graphs, as Marc suggested.

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

[drvinceknight]

Two suggestions to give us a relative discussion point:

• A streamlined README according to how I'm thinking about things: https://github.com/Axelrod-Python/Axelrod/blob/c0b33eee7d980cf491c7e250e73025a093f3a3e7/README.rst
• The same README with two plots: https://github.com/Axelrod-Python/Axelrod/blob/354c7ae6bf3330a037ea573bb2be108ad0ab7f29/README.rst

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.

[marcharper]

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.

[drvinceknight]

I've really read any words.

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.

I think maybe three plots: a tournament, a heatmap, and a fingerprint, perhaps. I also recommend a few lines for running a match + sparklines.

Cool, I'm not averse to that, @marcharper do you want to perhaps take a stab on top of that readme-revamp branch: https://github.com/Axelrod-Python/Axelrod/blob/readme-revamp/README.rst?

[drvinceknight]

do you want to perhaps take a stab on top of that readme-revamp branch

Feel free not to of course, if you think that's setting off in the wrong direction to begin with :)

[meatballs]

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:

• IPD researchers - they will know all about the basics already and will want to know what this library can do that they cannot get easily elsewhere
• Pythonistas - Those who have perhaps found us via the python community and know little about IPD but would join us if it looked sufficiently interesting

[marcharper]

I'll give it a go.

[drvinceknight]

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

[drvinceknight]

#1072 refactored the README. Closing but reopen if it's not felt that's sufficient.

[drvinceknight]

@marcharper can you clarify what you still want done for this?

[marcharper]

I'll open a PR or close the bug if I'm happy soon

[drvinceknight]

👍