Docs Discussion

[marcharper]

@langner @drvinceknight | follow up from #534

We've been chatting in gitter about updating the docs... I'm inclined to agree now that the first page docs ought to be as easy as possible to digest for newcomers. In that regard I suggest that we focus on matches before anything else. IMO they are the easiest chunk to understand, and we could even point at a "gentle intro" jupyter notebook (perhaps a simplified version of this one).

We should also consider a "for the experts" or "advanced topics in detail" page.

[drvinceknight]

For reference I went and grabbed this issue: #299 which is what started the first revamp of the docs. The very first set of documentation was terrible, it was a long "story". Following #299 we moved towards a more modular setup which I think has worked well so far and unless I'm misunderstanding is not what we're discussing? I think it's a question of classification that we need to agree on?

I'm inclined to agree now that the first page docs ought to be as easy as possible to digest for newcomers. In that regard I suggest that we focus on matches before anything else. IMO they are the easiest chunk to understand, and we could even point at a "gentle intro" jupyter notebook (perhaps a simplified version of this one).

This sounds like a great idea. We could have an extra "creating a match" here: http://axelrod.readthedocs.org/en/latest/tutorials/getting_started/index.html (so that section would have 3 sub sections: Installing, creating a match, creating a tournament.).

and point towards:

http://axelrod.readthedocs.org/en/latest/reference/description.html

I don't think it would need a lot for this introductory section. We want to keep things light so people can get started.

We should also consider a "for the experts" or "advanced topics in detail" page.

I agree. Here is where the classification/naming/labelling/description is important. I agree we should have a better landing page that describes what the "sections" enable you to do. I think describing who the sections are for is not ideal as self classification can go wrong (expert game theorist, never used python etc...). So I would prefer labelling what the section enable you to do.

Our current landing page http://axelrod.readthedocs.org/en/latest/index.html, says nothing.

My suggested labelling of the sections would be something more verbose:

1. "Getting started" -> "New to Python and/or Game Theory"
2. "Further topics" -> "Contemporary research topics"
3. "Advanced topics" -> "Further tools in the library"

(Based on that, I would actually suggest that the Moran process would go to 2. and the eco would stay in 1. I think we could also move Classification of strategies and Reading and writing interactions to file to 3.)

I think this ensures that the docs cater both to very beginners (as @langner says: those who have never seen the words game and theory together) but also researchers. One thing I can't wait to happen is when someone other than us writes a paper using this library (without us). Our landing page could clarify all this.

1 other thought I think we should keep in mind: I am not aware of anyone saying the current set of docs was unclear/unhelpful. I've heard the opposite a handful of times. So I think we should be careful to revamp everything. Perhaps I'm wrong and things are broken from a user pov and do need fixing. What I believe is broken is our (core devs) thought process as to what each section corresponds to. I think the above clarifies this (but no doubt it is not final)?

EDIT: "clarifies this" -> aims to get us on the same page (perhaps my suggestion is not the right page but that's what we should aim for.)

[drvinceknight]

By the way: I'm super glad we're having this discussion. It's important that we always look back at these things and make sure we're doing as well as we can. 👍

[marcharper]

I prefer the Moran process as the "simple" and standard population dynamic because it's easy to motivate and can be launched with the same amount of code as a match or tournament:

>>> import axelrod as axl
>>> players = (axl.Cooperator(), axl.Alternator())
>>> match = axl.Match(players, 5)
>>> match.play()

>>> import axelrod as axl
>>> players = (axl.Cooperator(), axl.Alternator())
>>> mp = axl.MoranProcess(players)
>>> mp.play()

>>> import axelrod as axl
>>> players = (axl.Cooperator(), axl.Alternator())
>>> tournament = axl.Tournament(players)
>>> results = tournament.play()

The ecological tournament is a further step, and it's not really clear what an ecological simulation has to do with a round-robin style tournament:

>>> import axelrod as axl
>>> strategies = [axl.Cooperator(), axl.Defector(),
...               axl.TitForTat(), axl.Grudger(),
...               axl.Random()]
>>> tournament = axl.Tournament(strategies)
>>> results = tournament.play()
>>> eco = axl.Ecosystem(results)
>>> eco.reproduce(100)

I get that the ecological simulation is easy to form from tournament output. My issue with the ecological variant being in the "simple introduction" is that it's almost entirely unmotivated by the docs:

To study the evolutionary stability of each strategy it is possible to create an ecosystem based on the payoff matrix of a tournament:

How is the ecological variant connected to evolutionary stability? I'm not sure that it is. I can imagine a population of organisms evolving via the Moran process... I'm struggling to connect the ecological simulation with the dynamics of a population. For the Moran process it's known how the process outcomes and transition probabilities connect to fixation probabilities, to definitions of evolutionary stability, etc.

Superficially one might think that the two simulations are closely related. However for the ecological simulation there is a nonstandard variation (in-line comments from the code):

Note that we sample the normal distribution based on the payoff matrix and its standard deviations obtained from the iterated PD tournament run previously.

This assumption is evidently incorrect -- our other simulations show that in many cases the distribution of scores between two opponents is not normal (just look at AllCorAllD, which often produces a bimodal distribution of scores).

So my concerns are:

• Newcomers won't understand the what the ecological simulation is actually doing
• Newcomers could be misled by the output of the ecological simulation
• Newcomers will get the wrong impression regarding how population dynamics are studied

and

Experts won't see what they expect.

[drvinceknight]

OK. That makes sense, I'm happy to follow your guidance. Let's put Moran in to the 1. and Eco in to the 2.

What do you think of the suggested minor restructure/rename?

[drvinceknight]

By the way - side point - (these code snippets really summarise it all for me) the following works:

>>> import axelrod as axl
>>> players = (axl.Cooperator(), axl.Alternator())
>>> match = axl.Match(players, 5)
>>> interactions = match.play()

match.play() returns the outcomes as well as setting them.

For consistency I think it would be really cool if this worked:

>>> import axelrod as axl
>>> players = (axl.Cooperator(), axl.Alternator())
>>> mp = axl.MoranProcess(players)
>>> populations = mp.play()  # mp.play returns the populations

I think these 3 code snippets could almost be our landing page, or perhaps a quick start guide...

[marcharper]

I'm with you on all the other points -- I should have led with that!

I like suggestion for the return value of mp.play() as well.

[drvinceknight]

OK sounds like progress. OK for me to pick this up? I'll get a PR in tomorrow :) (I'll do the mp.play() in there).

[drvinceknight]

Have opened #539 :)

[drvinceknight]

Closed by #539.