-
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
Docs Discussion #536
Comments
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?
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.
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:
(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 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.) |
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. 👍 |
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:
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:
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:
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:
and Experts won't see what they expect. |
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? |
By the way - side point - (these code snippets really summarise it all for me) the following works:
For consistency I think it would be really cool if this worked:
I think these 3 code snippets could almost be our landing page, or perhaps a quick start guide... |
I'm with you on all the other points -- I should have led with that! I like suggestion for the return value of |
OK sounds like progress. OK for me to pick this up? I'll get a PR in tomorrow :) (I'll do the |
Have opened #539 :) |
Closed by #539. |
@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.
The text was updated successfully, but these errors were encountered: