
Zed Shaw completes mongrel2 manual - RyanMcGreal
http://mongrel2.org/doc/tip/docs/manual/book.wiki
======
nailer
"TCP

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.

~~~
zedshaw
Ah, I'll take a look at that, but actually I was describing 0MQ not TCP. Did
you mean I should describe what 0MQ is first?

~~~
nailer
The preceding sentence is:

"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_.

~~~
zedshaw
Done:
[http://mongrel2.org/tktview/b685326bc0ded7a466b61fb0d1c6e7d5...](http://mongrel2.org/tktview/b685326bc0ded7a466b61fb0d1c6e7d598c5a5d4)

I tend to spew at the mouth then tighten it up later.

~~~
nailer
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.

------
elblanco
Zed is clearly in the wrong business. He's such a prolific writer, he should
really be rewriting and updating the O'reilly catalog.

~~~
jpeterson
He'll have to learn how to write without insulting and alienating half his
audience.

~~~
zedshaw
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.

~~~
jpeterson
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.

~~~
zedshaw
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.

~~~
rgejman
Zed,

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?

------
zrail
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.

~~~
jamii
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.

~~~
zrail
The "runit" binary itself is supposed to replace init. If you want to use
runit as a user-space process manager you have to use runsvdir and friends.

~~~
jamii
Yes, I was calling runsv and trying to bring it down again with sv. I suppose
I should have been specific.

------
mpk
Yeah, completes documentation on a product he announced an intention to
develop 5 seconds ago (internet time).

Gotta respect the guy's work ethic and coding chops!

~~~
ewald
People can say whatever they want about Zed, but they can't say he doesn't get
things done.

~~~
mkramlich
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.

~~~
bandushrew
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.

