Programmers think these are streamed sequential messages, so if they send a ”message” that’s 10k long then when the receiver gets it and read from the TCP socket they get a single 10k message in reply. This only works in small messages and not on the internet, so it’s easy to see how it would seem to work that way. The reality is you can get messages of any size, and without some framing mechanism you wouldn’t know where one messages ends or beings. TCP is a streaming protocol.
UDP
Programmers think UDP sockets are single fast reliable messages that can be sent to one or more target clients. They at least know UDP has a fixed upper bound size, but they don’t get that UDP is very unreliable and that the addressing is fairly weak.
"
Writing tip: start by saying what they are, rather than what they're not. People may not have existing notions to shatter. A lot of Django documentation suffers from this too: 'before frameworks, you would have..., but not with Django' isn't relevant if you're learning to program with a framework.
"What ZeroMQ ends up being is ”sockets the way programmers think sockets work.” Programmers usually hear about TCP or UDP sockets and they think in a naive way that they work like this:
"
Which makes me think you're talking about TCP or UDP sockets outside of 0MQ.
There's also some tightening you could do in your opening paragraph about why Mongrel 2 is awesome. How about this for an intro:
Mongrel 2 is awesome for the following reasons:
* It can serve both traditional web apps and realtime push-style apps, where the server sends stuff to the clients when you need - great for making chat apps (there's one included in the sample code), stock sites that sends updated pricing to browsers, live blogging updates about news events as they happen or anything else you can think of.
* You can make Mongrel apps in your preferred language - PHP, Ruby, Python, C++ now, more soon. You can even configure it in that language.'
You say all these things now, but you're currently using too many words. Make it tighter.
Cheers. If it's not obvious, it's me who's bugging you about task-based stuff on Twitter. I spent a few years writing professionally and have a somewhat thick skin of my own when it comes to the editing pen, so pardon if I'm a little insensitive in the suggestions.
* You are, genuinely, missing a few 'open your browser, hit this port and try it' bits per Twitter. yes we're looking at the same doc, but I think you're presuming people will actually open their browsers and look at the http://localhost:6767/tests or whatever, rather than being told to do so. You also don't show or mention what people can expect to see when they visit this. Throw a screenshot in.
* The sections about Steve and Knuth, sysadmins who can't code, and alternative inits you've tried but not liked, can be removed. They distract from the topic at hand. I read the bit about 'insulting to keep you interested' but it doesn't lend the doc character: it comes off like you're bitter, and doesn't help the end user actually set up Mongrel.
* For config, first show people how to configure mongrel using the default Python config file. Once you've done that then point out that they can create their own config formats if they don't like Python or want to automate stuff. Mention MVC if you want, restrict it to one sentence at the end. The aim is to making a working web server - anything asides from that gets in the way. See Kathy Sierra's stuff about 'helping users be awesome' for some good info on this.
* Be specific. 'Hacking' could be 'making web apps with Mongrel 2'. Per Twitter 'hacking' is ambiguous - think of the HACKING file in every GNU app which discusses modifying the program itself, rather than using it.
With a bit of editing, the current daunting manual could be about 50% the size.
This might be a programmer's quirk, I remember when I wrote my thesis, most of the corrections of my advisor were of this nature. Whenever I presented something I would start by enumerating the bugs and limitations, before finally saying what it actually could do.
Cognitively, it's not the best ordering for the information. Better to anchor something starting with the capabilities. Starting with the limitations is starting with zero, then subtracting. It's much harder to imagine negative dollars than it is to imagine a pile of cash with a bit of it taken away.
First off, I didn't insult you by name right? Which means I didn't insult _you_ I insulted your ideologies. To me there are no kings or heroes to worship. If you get offended because I disagree with you then you're not intellectually honest and most likely would get offended no matter what I say.
Second, it depends on the audience, but I plan on purpose to alienate 1/3 of my audience when I write technical documents like this. I focus on alienating the 1/3 of the audience who are arrogant, obnoxious, and too blind to see that their beliefs and values are killing the industry.
I just don't want to work with them, especially if they can't take a joke. Surprisingly, this turns out to be a very small number of people in practice, and they're usually just pseudo-intellectual blowhards.
If you go through all my insults, they're aimed at the people who are screwing things up for the regular Joes trying to get things done. And _that_ is the entire purpose of the Mongrel2 project too.
I never said you insulted me. I quite enjoy your writing, and belong to the half of your audience who doesn't give a shit.
My point is that your style is very personal and confrontational. You usually start discussions by aggressively speaking out against programmers or certain types of programmers, and only after this move on to any specific work that they've done or their ideologies. What you're really trying to criticize is the work.
There's nothing inherently wrong with this, of course. But it probably sets an unnecessary upper bound on your readership.
Oh, well my appologies then, I was assuming you were offended (there's plenty of them :-)
Actually, quite the contrary. Even the people who hate that I insult them still read it...and then talk about it for days on end like they have no lives.
I also belong to the ranks of people who don't get offended when you insult people. But I wonder what you gain from it. 1. How do you know that the people who do get offended are the same people you don't want to work with? 2. How do you know that ranting actually deters these people from using your products?
My point is similar to jpeterman's, but my focus is on how you know that you are actually setting and upper bound on your readership, and if you are, how do you know that you are benefitting?
"First off, I didn't insult you by name right? Which means I didn't insult _you_ I insulted your ideologies."
I speak for myself, not for the supposed audience you're alienating, but I simply do not like your tone. That doesn't mean i'm insulted or offended, but it simply means I don't like it when people feel the need to vent in such a harsh manner.
Having said that, I do respect you for putting your money where your mouth is.
That's my feeling exactly. Too often the manuals and documentation people read are a chore to get through because they're so boring. They're also passive aggressive because they're obviously saying their technology is better in some way, but they're trying to be nice. You read through and there's little lame attempts at being the next Oscar Wilde when really it'd be much better if they just came out and started a fight.
When I write my docs I want it to teach people how to use it, and not put them to sleep at the same time.
Let me clarify what I mean. Zed usually takes this approach: "Here is something that idiot programmers do; let me show you the right way."
Half his audience will read this and think, "Gee, I don't want to be an idiot--I should continue reading!". The other half will take it as an insult, or just find it to be in bad taste, and put the book down.
A good writer should be able to get across his message without insults.
Actually, he'd make a fantastic tag-team with _Why. It would be a little like Abbie Hoffman & G. Gordon Liddy on the same speaking tour. Not to say these guys are on analogous points of the political spectrum (couldn't care less) but that they have markedly different points of view and would have a very interesting antagonism.
I have no idea how those two would ever co-write a book though. I bet that would sell, however.
"In case you haven’t figured it out, this book will be fun and slightly obnoxious. That’s not intended to insult you, but just to keep you interested so that you want to read it."
He might just be better off writing his own and self-publishing. I would definitely pay for anything by Zed on .net - I've not found any readable alt.net authors - Ayende just confuses me! Can anyone recommend anyone?
I'm running an informal "Learn Python the Hard Way" study session on Tuesdays at Antidote Coffeehouse in Houston with some friends of mine. I have some nerdy non-programmer friends who have long expressed an interest in learning how to program, and we've tried a few different things ("NAND to Tetris" and a a different type-in Python games tutorial) but "The Hard Way" is much better focused on the complete programming newbie. I've also taught Comp Sci 101/102 as a grad school TA. I have to say that "The Hard Way" is markedly better than all the other attempts at a tutorial for the complete programming newb I've seen.
A valuable area to target: Concurrency Optimization. Another: Low-Level Optimization and Memory Hierarchy. Books on these already exist, but Zed has the attention of a large swathe of the programming populace that could really use more awareness on these topics. That potential energy could be converted to book sales or sales of some sort.
Hey! This is awesome. Can you do me a favor and take notes on lessons that they screw up, then submit bug reports? I put it out there and then I know people are using it but I don't get any feedback. Short of running my own intro class I can't find any other way to get information on whether it's working.
Either it's working so damn well nobody needs to tell me because they end up writing their next million dollar idea a week later, or it's really not working and people are just not bothering to tell me.
Sure thing, Zed. I'll plant the idea of remembering the stumbling points and generating feedback.
Two of my friends have commented that they really like the snarky humor. I think it's a part of what keeps them chugging through the designed-to-generate-errors-you-must-debug drudgery.
EDIT: Going back over the book, Exercise 0 caused one of my friends some confusion. The other sailed through it just fine. The confused one is a Windows user and hadn't seen the command line since Windows 3.1. The non-confused one has an Ubuntu netbook. Confusion was over what constituted commands to type in and what was the part you should see. The mode switch between the Python prompt and the CMD command line also took a few minutes of explaining.
Ah interesting, yeah I don't have windows so someone else submitted those instructions. I'll go and try to do them myself and see if they can be improved. Although, I think for windows folks this will be a big hurdle at first either way.
It's a minor point, but procer is basically exactly the tool I've been looking for. We're using runit to launch processes and getting runit to actually, you know, run has been a major pain in the ass, and it's really weird. And the c code is horrible.
Without having looked at the code, is there any way that procer could be made a standalone thing? I don't think I'll be able to get traction on mongrel2 anytime soon, but procer I could use today.
Edit: I looked at the code. Looks pretty tied into mongrel2. I might just take the ideas and run with it, though.
I was trying to get runit to work last week and it consistently broke my terminal. After calling runit nothing I typed would show up, including newline.
Tons of people are getting things done everyday around the world. Zed happens to be part of the subset who are promoting themselves agressively on the web. Not that I think that self-promotion is bad. But it's important to recognize the distinction between promotion and productivity.
I have been thoroughly impressed with how productive Zed can be.
whether or not he is good at promoting himself - and he seems to negatively affect enough people that the point is arguable - he is good at getting things done, people who fail to acknowledge that reveal more about themselves than they do about Zed.
Programmers think these are streamed sequential messages, so if they send a ”message” that’s 10k long then when the receiver gets it and read from the TCP socket they get a single 10k message in reply. This only works in small messages and not on the internet, so it’s easy to see how it would seem to work that way. The reality is you can get messages of any size, and without some framing mechanism you wouldn’t know where one messages ends or beings. TCP is a streaming protocol.
UDP
Programmers think UDP sockets are single fast reliable messages that can be sent to one or more target clients. They at least know UDP has a fixed upper bound size, but they don’t get that UDP is very unreliable and that the addressing is fairly weak.
"
Writing tip: start by saying what they are, rather than what they're not. People may not have existing notions to shatter. A lot of Django documentation suffers from this too: 'before frameworks, you would have..., but not with Django' isn't relevant if you're learning to program with a framework.