Random thoughts as I read through it.
It'd be nice to have a curl https://raw.github.com/technomancy/leiningen/stable/bin/lein > ~/bin/lein in the README instead of a link that goes somewhere... to the script itself? or to a GitHub page for it? I don't know until I click it.
The README tells me to go to the tutorial but there's a bunch more important-looking information like Configuration, Profiles, etc. Do I need to read those or will they be covered later?
The FAQ is pretty long and in-depth, might be better to move it out of the README.
The other sections are good, I'd keep those.
Creating a project part is good.
Packaging is next... I think it might be better to show the user how to actually do something useful. lein repl would be perfect to introduce here because they can actually see some Clojure code working and returning.
I'd also show them that lein repl sets up their classpath by having them do something like this in the repl:
(use 'my-stuff.core)
(some-fn-thats-defined-in-the-core-ns-in-the-default-project-skeleton)
Getting a "black triangle" on the screen for them as soon as possible so they can see their code in their files actually flowing through the system gives them a sense of "whew, okay, I can see roughly how this works".
Save packaging for the end, if you even talk about it in the tutorial. I think you could split it into a separate document even -- it's not critical to your first 20 minutes with Leiningen.
I'd also go ahead and introduce lein run here. It's very UNIXy and will feel familiar -- similar to Python/Ruby/etc's "run command to run your program". Tell them about the command, what code it runs, and how to change that. Show them an example.
The project.clj section is next. It's fine -- the description/url are trivial and easy to figure out.
The dependencies section is next. I think lein search here is bad. I know you mention that it takes "many minutes", but that doesn't adequately convery how painfully slow this is the first time you run it.
I started running it on my laptop when I read this and expected it to finish later and I'd come in and fill in the time it took... well it's been going for 10+ minutes, I finished the rest of the tutorial, and it's still not done. And I have a fairly nice internet connection.
That's way more than any other command and pretty much stalls the user in their tracks. As a new user I'd be turned off and probably close the window after the first minute or two.
I think the best solution is to fix lein search itself. First: it needs a progress meter. All I see when I run it is this:
$ time lein search math
Downloading index from central - http://repo1.maven.org/maven2 ... this may take a while.
No indication of how long it'll take, not even a file size so I can guess based on what I know my internet connection to be and go and get some coffee. There's not even any way to know it's not frozen without looking at my network throughput.
An alternative would be to fix lein search to just not be slow in the first place. Maybe make a simple web service that performs searches for the user or something. I don't know what's easiest, but a download in the basic tutorial that takes longer than it took me to critique the rest of this document is a bad idea.
Okay, so aside from lein search being painful this section is pretty good. I'd skip talking about lein install -- no one needs that right away. Mentioning that packages are cached locally is a good idea though.
Talking about the structure of the magic dependency vector is good -- it took me a while to figure that out.
The whole Profiles section feels like it doesn't belong here. It glosses over stuff and it's not critical to get started. I think it'd be better as its own document.
The "Writing the Code" section is all about lein test -- call it "Running Tests" instead. Test selectors aren't important in the first 10 minutes -- move them to a separate "All about Lein Test" doc.
Lein needs a lein autotest command that automatically reruns lein test whenever files change on disk. That would make all the silliness about REPL'ing run-tests or installing editor crap unnecessary.
Pull out the AOT compilation -- I've needed it once in the ~2 years I've been using Leiningen so it certainly doesn't need to be in the initial tutorial.
I like the next section -- it's more of a high-level roadmap for users which is really nice.
The uberjar section looks good, same with server-side projects.
The publishing libraries section seems to skip the "Get an account on Clojars" step... is that no longer necessary? Also what happened to lein push instead of some crazy scp command?
I think that's about it. Overall it looks pretty nice, the following are my main issues:
- Introduce
lein replandlein runright away to give users their black triangle and make them feel like they're getting somewhere. - Fix
lein searchto not suck the first time it's run. - Skip the scary Javaish/Maveny stuff like
lein installand AOT compilation in the basic tutorial. - Save profiles for a separate document.
- Make a
lein autotestcommand to make users' lives easier.
While the autotest sounds nice, that will be a pain to get it to work on Linux/OS X/Windows in the same quality/ease of use.
I disagree on skipping lein install. If you have a project like leiningen itself, with a contained core bundle that's a dependency of the parent bundle there's no way around it.
Speaking of leiningen itself, a small "how to hack on leiningen itself" would be nice, took me some time to figure that part out yesterday :P (reformatting the release checklist would suffice I think)