News for hackers. Stuff that matters.
Re:Zed Shaw completes mongrel2 manual by nailer on Friday July 30, 2010 @11:16AM (#1561358)
"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.

Re:Zed Shaw completes mongrel2 manual by zedshaw on Friday July 30, 2010 @02:48PM (#1562151)
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?
Re:Zed Shaw completes mongrel2 manual by nailer on Friday July 30, 2010 @05:58PM (#1562746)
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.

Re:Zed Shaw completes mongrel2 manual by zedshaw on Friday July 30, 2010 @08:05PM (#1562946)
Done: http://mongrel2.org/tktview/b685326bc0ded7a466b61fb0d1c6e7d5...

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

Re:Zed Shaw completes mongrel2 manual by nailer on Monday August 02, 2010 @04:50AM (#1567191)
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.

Re:Zed Shaw completes mongrel2 manual by lkozma on Friday July 30, 2010 @12:27PM (#1561654)
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.
Re:Zed Shaw completes mongrel2 manual by stcredzero on Friday July 30, 2010 @02:18PM (#1562051)
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.
Re:Zed Shaw completes mongrel2 manual by lkozma on Friday July 30, 2010 @03:01PM (#1562200)
Sure, I agree, I didn't say it was a good way to present things, just that it might have something to do with how programmers think.