Fleshed out README and design goals

[f0k]

This fleshes out the README file to show an example upfront so you know what to expect, and to point to installation instructions, documentation and contribution guidelines (although the latter should probably be fleshed out in the documentation).

See https://github.com/f0k/Lasagne/tree/readme for how it would look.

Closes #86 in passing.

[ebenolson]

Looks good, but I think the installation and documentation sections should be closer to the top. A blurb about Recipes would be nice also.

[f0k]

Agreed, the example scrolls other important aspects out of view. It's usually nice to have it on top, but for most projects it's a lot shorter. I can add a link to "Recipes" to the Example section. What'd be your suggested order of sections then?

[ebenolson]

I'd go with something like

• Lasagne
• Installation
• Documentation
• Examples
• Design Goals
• Development

[f0k]

Reordered. Maybe move "Design Goals" before "Installation"? It looks a bit lost where it is. (But it also is quite long and would push other sections outside the view.)

[benanne]

Very nice work! Had a quick look at it but couldn't find anything to nitpick at :)

[f0k]

I'm thinking about removing "Design Goals" (but linking to it, they're in the documentation anyway) and adding some bullet points about Lasagne's features instead. I'll try that later.

[f0k]

I've removed the design goals and added a list of features instead. What do you think? Is there anything wrong/misleading/missing? (See https://github.com/f0k/Lasagne/blob/readme/README.rst for a nicely rendered version.)

[dnouri]

I'd drop the 4x "Support for", it's repetitive.

[f0k]

That's right, but it felt weird to list "feed-forward networks" and "architectures" as features. We need a different introduction for the list then, one which fits "Feed-forward networks", "Optimization methods", but also "Designed to be easy to use and easy to extend". I'll figure something out.

[f0k]

Didn't find a good way to drop the repeated "support for", there's no unifying introductory sentence for all the bullet points then (especially the last one sticks out). Instead I merged the first two and reworded the other two. I dropped the explicit list of "Multi-Layer Perceptrons (MLPs), Convolutional Neural Networks (CNNs), Long Short-Term Memory (LSTM) and Gated Recurrent Units (GRUs)" because it was long and not exactly aesthetic, but I think these would be good keywords for google. Maybe we can later add a bullet point with "Includes examples for ..., ..., ..., ..." along with links once we have them.

I've also extended the example to include training and testing.

Any objections against squashing and merging?

[benanne]

I kind of liked having the design goals up on the front page of the github repo, because I think they're really important and basically what set Lasagne apart from many other neural network libraries. This also ensures that everyone considering contributing has at least seen them. But I guess we should probably be shifting to catering towards users of the library, and not necessarily to contributors. So I'm okay with getting rid of them if most of you think that's better.

[dnouri]

I kind of liked having the design goals up on the front page of the github repo, because I think they're really important and basically what set Lasagne apart from many other neural network libraries.

I had the same thought. +1 to putting design goals back.

[ebenolson]

Focus: follow the Unix philosophy of “do one thing and do it well”, with a strong focus on feed-forward neural networks.

I think this at least should be revised in light of #294.

[benanne]

I guess so :) Although the design of the library is still pretty much focused on feedforward architectures, and RNNs were sort of built on top of that. I feel that some alternative libraries treat RNNs more like first-class citizens than we do, e.g. Blocks. But I'm okay with rephrasing it nevertheless.

[f0k]

Ok, but where would you put the goals then? I think they're quite long in their current form, taking the focus from what I think are more important parts (the example and the installation instructions). I tried to include the most important design goals in the features list, namely the focus not only on easy usage (which doesn't set us apart), but also on extensibility (this is important when we're targeting researchers) and modularity (that's important for users coming from Theano and not wanting to completely switch over to a new library). Shall we continue that route, or include a somewhat shorter description list of design goals? Shall we put it after the list of features, or into the "development" section? Finally, does anybody of you want to help with this? (Copying and pasting the design goals from the Sphinx documentation is something I can easily do myself, but I don't think that's a good solution.)

[craffel]

I guess so :) Although the design of the library is still pretty much focused on feedforward architectures, and RNNs were sort of built on top of that. I feel that some alternative libraries treat RNNs more like first-class citizens than we do, e.g. Blocks. But I'm okay with rephrasing it nevertheless.

At this point I don't think there's any way that RNNs are not as much of first-class-citizens in lasagne, aside from the fact that you and @f0k don't use them ;) Given in particular that we have made a good handful of design decisions motivated by them (and will probably make a few more ).

[benanne]

Depends how you look at it, really. I feel that the whole 'layer' paradigm is just inherently more suited to feedforward architectures than recurrent ones. You can nest recurrence within a layer, but that's not quite the same as treating it as a "first class citizen" imo.

Please don't get me wrong, this is not a value judgement of having recurrence in the library or anything, just an observation. I am in fact very happy that we have some high-quality code for supporting recurrent nets!

[craffel]

Depends how you look at it, really. I feel that the whole 'layer' paradigm is just inherently more suited to feedforward architectures than recurrent ones. You can nest recurrence within a layer, but that's not quite the same as treating it as a "first class citizen" imo.

Yes, but I think treating recurrence in another way is likely cumbersome; I see the layer architecture as just a straightforward way of building hierarchical networks in general - feedforward or recurrent.

Please don't get me wrong, this is not a value judgement of having recurrence in the library or anything, just an observation. I am in fact very happy that we have some high-quality code for supporting recurrent nets!

No worries, I see your point. I think the risk of stating that the main focus of the library is feedforward networks is that it will turn away people who are interested in recurrent networks needlessly, which is I think what @ebenolson is getting at.

[f0k]

I kind of liked having the design goals up on the front page of the github repo, because I think they're really important and basically what set Lasagne apart from many other neural network libraries.

Okay, I've put a shortened version of the design goals back in: https://github.com/f0k/Lasagne/tree/readme
They capture what I think is the essence of each of the goals. I like the look now, but I think the goals are not thought out well yet. I'll add some comments to the diff (although this PR is getting a bit out of hands).

[f0k]

This is very closely related to "Simplicity". In the long version, it even says "This should make it easier to both use the library and extend it". I'd merge it with Simplicity or drop it.

[benanne]

I'm okay with merging them :)

[f0k]

Thanks for the feedback, Sander! I've rewritten the design goals a bit (both in the README and in the documentation). I'm quite satisfied with the result.
The only thing I'm slightly unsure about is finding a noun capturing what was previously called Don't get in the way. For now I've chosen Restraint, in the sense that we try to constrain the effect of features on users, or in the sense that the library doesn't put every feature in every user's face. I was actually looking for something that describes how the interface is supposed to be clean and unobtrusive until you need something. Like being in a room with curtained walls, and you only pull aside the ones you want. I'm open to suggestions, but very keen on keeping it a noun, to go well with the others, or a single adjective.

In any case, I'd like to bring this PR to an end, squash and merge it, it wasn't intended to run forever! :)

[benanne]

I thought "don't get in the way" was a little more immediately obvious. I'm not sure if there's a nice noun that captures the same essence (and that most people would understand). But the description is unambiguous so I think 'restraint' is fine for now :)

[f0k]

I thought "don't get in the way" was a little more immediately obvious.

It sure is, but stylistically it sticks out too much for my taste :)

Sooo... any objections against merging from anybody involved in the discussion? (I'll squash the first 6 commits into one before merging.)

[ebenolson]

I think it would look better without the bold, it contrasts with the feature list above and draws focus.

I also think there's still a lot of overlap among the principles, but I don't have any very useful suggestions for that.

[f0k]

I think it would look better without the bold, it contrasts with the feature list above and draws focus.

Okay, I can take care of that when squashing. (I'll also remove the "[coming soon]".)

I also think there's still a lot of overlap among the principles

Yes, but I think it's better than before, and some overlap may make things easier to understand. For example, what we have for "Transparency" is already implied by "Simplicity" and "Modularity", but I think it's still useful to write it out. And what we have for "Restraint" is an aspect of "Pragmatism", but for some design decisions it may be easier to point to the former than to the latter.

but I don't have any very useful suggestions for that.

Good, let's leave it at that then! We can always change it later, PRs are for free on github ;)