CS Students: Learn to Write    Posted:


Writing Hand

If I could do my college years over I would focus on writing. I would take courses that required a lot of writing, in the spirit of "learn by doing". I'd also take courses in the mechanics and craft: grammar, vocabulary, and rhetoric.

I used to consider myself a competent writer. And certainly good enough for an engineer, right? But I've learned that I have a long way to go. I've learned that engineers spend much more time writing than you expect. And I appreciate how hard it is to write well.

This came up just this past week. I came across a beautiful four page essay. It laid out the problem, described alternatives, and lead you concisely to a well-reasoned conclusion. Sure, it was about technology, but what carried the day was the good writing. Humbling!

You're saying: but wait, you're a pointy-haired boss now Sef, one of those guys who doesn't do Real Work anymore. You write email and boss people around. I understand why managers like you need to write, I'm an engineer. I write code. Well, there's some truth to that. But I'd like to convince you that even monster coders, if they're any good, write a lot, write well, and value good writing in others.

It is rare for someone to do their work in isolation and have it matter. Either you're working as part of a team, in a company or a community of developers, say on an open-source project. Sure, you build a great system or feature. But to have it matter to the world, for others to adopt it, you need to document, publicize, support, teach. 98% of that is writing.

I had a lunchtime conversation with Jacob Kaplan-Moss, Django's co-founder, at last year's PyCon. I asked him why Django caught on and was adopted by so many of us (including my last project and my current project). I was expecting him to point to features or timing. Instead he said it was "because we wrote good docs". The Django team didn't treat documentation as an afterthought. They have lots of docs, and they are good.

Consider that rare bird, the iconoclastic engineer working in isolation on their own project. I'm thinking of Antirez or Marco. (Maybe they aren't even truly on their own so much. Humor me!) They are prolific and strong coders. But they also write a lot of words! They write a ton about their project; also tech landscape and their place in it. Would their software have as much of an impact if they didn't write so much (and well)? I say no.

Case in point. Both Marco and I wrote blog posts riffing off the same topic two weeks ago. First, read mine, then his. It takes me a ton of words to get something basic out. His is concise and clear. Sheesh.

So kids, don't shortchange those liberal arts classes. It's not fluffy stuff on the side. That is core. You need to write well to be a good engineer.

Protip: the best way to do this is to major in the humanities. They write like crazy over there. Be like my friend Dan Chu and major in history, but secretly take CS courses on the side. If you're super smart like him, and can manage getting both degrees, then you're awesome. But don't sacrifice the BA for the BS. I would love to talk to a candidate with with a History BA and a Computer Science MS.

Comments

Chicken Soup    Posted:


Yummy Bowl of Chicken Noodle Soup

My family hasn't avoided the colds that are going around now. My way of fighting back is making chicken noodle soup. It's not too hard, it's satisfying, and it tastes great. The recipe belongs to Peninsula School and gets used at our annual Craft Fair. It's benefited from years of refinement.

I add more salt. I don't do peas. I've tried with rice but it got starchy and weird, stick with egg noodles.

Comments

Consume vs. Produce vs. Produce Publicly    Posted:


\

One of my goals for this year is to try to produce more and consume less. Not in the green, fixed-planetary-resources sense [1]. I mean to make more things, ideas, contributions. To be more creative. Creative in literal sense of that word: creating.

Rands said it well in his post this week, "The Builder's High'. If you haven't read it, go do so now. I'll wait. (and while you're at it, if you don't have him followed or bookmarked or whatever, do that too.)

I agree with pretty much everything he said in there. The good feeling that comes from actually making soemthing. How that's especially true now in light of the constant crush of everyone else's creations (he called them "moments").

Making takes many forms. Since I stink at woodworking and gardening and painting, I'll stick to the things I do enjoy, like writing and coding and cooking. Those fit less into the traditional mold of "building" or "making" but that's OK.

I want to take it one step further. Here are my three categories in value order. Numbers 1 and 2 we just spoke of, but 3 is new.

  1. Consume. This is watching TV, playing video games, trashy reading. Sure I'm going to keep doing that, but it's not energizing.

  2. Produce. Cooking a meal, learning something interesting. Maybe even reading something intellectually challenging, but that's pushing it.

  3. Produce, In Public. Now, this is the toughie. It's one thing to do something creative, another to put yourself out there and tell poeple what you did, and why. By sharing the product, by talking people through the choices you made to get there, you're opening yourself up to criticism. But why not!

That is part of the reason why I reworked my blog over the holiday break, so I'd have a nicer platform for writing. Anything to lower the bar to produce.


[1] I'm not anti-green. I really appreciate the environmental warriors out there who walk the walk with real life choices to consume less. That's just not my bailiwick, for now at least.

Comments

Switching to Static    Posted:


Nikola Tesla

For those of you who frequently read this blog (n ≈ 0) you'll notice that it looks a bit different. I've moved it from my own hosted Wordpress instance to static pages generated by Nikola and hosted up on Github.

Why bother? I didn't like my blog being something I wouldn't be proud to write or operate myself. Wordpress was overkill and not worth the trouble:

  • Wordpress is database driven for dynamic sites. My little blog isn't dynamic at all. Once you buy into the static idea, lots of otehr things fall into place.

  • Comments and account spam are still is a nuisance. The nice people at Akismet have done a great job holding back the tide, but I still get at least one bogus registration a day. I expect a service like Disqus or Facebook or Google+ will be more likely to keep pace with the spammers.

  • I want to author in markdown; maybe even ReST someday. All this wysiwyg-ish stuff in browsers is for the birds.

  • I don't actually need to host anything. I'm not running my own IRC server or anything. Even though Dreamhost has been a perfectly good service, I just want something... well, less Wordpress-ey.

Choosing

So I need to pick a static web site hosting package, specifically one that is good for blogs. The big things I was looking for: static site generation, Markdown/ReST support, and ability to host on free services like Github Pages.

In additon I wanted these things (in no particular order):

  • active development

  • in real use on real sites

  • easy customization, ideally by theming

  • ability to move over posts and comments, probably via Wordpress's export function.

  • python, what I program in for fun

  • a bit extensible

I considered three options before settling on Nikola. There are a ton of static site generators, even when you limit them to Python. But the only alternatives I seriously looked at were Pelican and Hyde. Of these Nikola seems to have the most active development and the richest set of features. I ease especially drawn by their good documentation and theming.

Up and Running

Here are my notes of what it took. This isn't a nicely-written howto, but if you want to see the blow-by-blow, read on.

  1. The software was easy to set up and get started

    • pip install nikola did the right thing. Of course within a virtual environment, you have to keep the lab clean!

    • Along the way I found a few other requirements, like request, phpserialize, and markdown. These were easy to find/fix because of helpful error messages.

    • This is all now captured in the project's requirements.txt.

  2. Initial import from wordpress XML dump went ok but a fair bit of manual HTML prettification took some time.

    • The slugs aren't how I like them: 201311seven-things.wp instead of seven-things.wp. I tried a bit to do mass rewrite of those, but couldn't easily do that without breaking everything, so just decided to let this go for now. I'll just do slugs without dates going forward.

    • I considered html2text but figured I'd just let the HTML slide for now. Too much trouble to go back and clean all that up now.

    • The "wp" extension, by default, is mapped to markdown instead of html. Odd but easy to change.

    • Nikola has a nice simple redirect facility that the importer pre-populated for me.

  3. Migrate threads to Disqus - clean and simple, worked right out of the box.

    • wordpress plugin has a nice import facility. Said it'd take a day, but didn't take that long at all. Aside from one thread with 75 comments, not much else that should cause them much heartache.

    • nice simple URL mapping utility

  4. Publishing to github. Again, easy peasy. The way to make this work is to put all your static files in a repo titled USERNAME.github.io. In my case: sefk.github.io. Just a couple of "tricks" were needed to make this work smoothly:

    • So that it would correctly serve my own domain, you have to put a CNAME file in the root of the repo

    • I put my nikola themes and source files in the "src" subdirectory, and changed the OUTPUT_DIR configuration option to ... Github Pages wants things in the root.

  5. The final swich. I moved my domain from Dreamhost over to Gandi, which is the registrar I like to use. They throw in basic DNS with registration, which is sufficient for me.

So There You Have It

So far I am really pleased with the result. It's a bit more work to publish, but for me that's natural and what I want. I guess I wouldn't recommend this to someone who isn't adept with all these bits (virtual environments, DNS, github repos, etc.) but for me that's no problem.

Thanks to:

Comments

Airmail FTW    Posted:


airmailFinally a thick-client email program that seems to have stuck. So far I am really liking Airmail.

For years I've flipped between various Mac fat clients and the GMail web interface. The web interface keeps winning:

  • Outstanding search
  • Great keyboard shortcuts (go Vi!)
  • Very good use of screen real estate

But the killer is the reliance on a rock-solid Internet connection, and GMail's own slowdowns. Even though there is an offline mode, it is such a downgrade it's not worth using. So if you need to use offline you're in bad shape; same if you're on a slow or lossy connection, or if GMail is having a bad day.  Sadly, that's pretty often these days.

Airmail is cheap ($1.99 in the App Store) and super featureful. It coexists well with GMail's paradigm (archive vs. delete, threading includes sent items, drafts). Great configuration options. Visually pleasing. Robust.

There are really only three places where it has fallen short for me:

  • I miss GMail's tabs. Those are still the best way to filter mail, and I was impressed with how well that feature worked and quickly became natural.
  • Search. Airmail's isn't bad, but nothing is as good at this as Google's own.
  • Gmail (with Chrome) has a great feature where you can drop in a picture and it is resized to look good.  Lacking that I now have to manually resize my giant retina-display screenshots.

So-long to Sparrow and Mail.app and Mailplane. Or until someone does really nails self-hosting.

Comments

The Seven Things You're Not Supposed to Talk About    Posted:


lucy-charliebrown

I liked this week's episode of This American Life. The idea is there are seven topics that you should avoid in conversation because they are always boring. I like this list!

Here is the transcript.  I repeat the list here.

  1. How you slept.
  2. Your period.
  3. Health. Of course if it's something serious, then that's conversation worthy, but normal sniffles, aches, and pains? No good.
  4. Your dreams.  Not big aspirations, this is literally what you dreamt last night
  5. Money.
  6. Diet. What you can and can't eat.
  7. Route. How you got here, what way you're going to get home.

I will endeavor to not waste all of your time droning on about any of these topics.

Comments

Halloween Down 20%, But Still Solid    Posted:


halloween2013-ticker

This year we had a sizable number of trick-or-treaters at our house in the Willows neighborhood of Menlo Park. The 303 we saw was down from our high last year, but abou the same as the year before that.

So here are the totals:

halloween2013-total

The rate at peak was comparable to last year.

halloween2013-rate          halloween2013-cumulative

I don't have an explanation why we are down a bit. The weather was beautiful, indeed a little better than last year since rain started at 8:30 last year. Maybe the forecast rain coming last year got people out earlier who might have missed altogether?

It was outstanding having my friend Amy LaMeyer helping out. She operated the clicker that was new this year, and so kept me company, which was a ton of fun.

As always, the Google Spreadsheet with the graphs and raw data is publicly available here. Check it out!

Comments

K&R C Programming, Quantum Books, Cambridge, MA    Posted:


IMG_4177

Today in a box I came across my old K&R. Probably the most valuable book I've owned. My copy has been heavily used.

But the unexpected, fun thing was finding an old label on the back cover.

There is a lot in there.

IMG_4179

  • January 1994. I had just graduated college, driven cross country with my friend Shig, and started my first post-college job. I would have been in that job four months or so and realized that I should just stop borrowing someone else's copy (probably Larry Claman's) and buy my own.
  • Purchased at Quantum Books, a great technical bookstore in the shadow of MIT in Cambridge, Massachusetts. It's no longer there. The bar that is there now (Meadhall) is a nice place, and I'm a big fan of beer, but it's not the same.
  • According to an inflation calculator, $35 in 1994 is $55 today. That's expensive for a little book, especially to the twenty-two year old me.
  • Note the email address: quanbook@world.std.com. This was back when mom and pop dialup ISP's where what we all used, people and businesses alike. This particular one, Software Tool & Die, was my private email address at the time too. (Aside: they claim to be the first public dialup ISP, and I have no reason to doubt them)

It was fun being reminded of all this stuff. So the lesson of the story: it's still worth buying books, and when you do, don't remove the labels.

Comments

Launch Day    Posted:


spaceshuttle

Today was launch day. It went really well.  I wanted to capture what a good launch feels like and contrast that with a more exciting launch, just five months ago.

Today we turned on our first class on Stanford's instance the open-source edX platform, what we're calling OpenEdX. The class is Statistics in Medicine, taught by Kristin Sainani of the Stanford School of Medicine. With over thirteen thousand students signed up it's a medium-sized MOOC (Massive Open Online Course).

We have launched MOOC's for Stanford before: two in Fall Quarter, and one in Winter. Even though the classes were huge success, but the launch days weren't so smooth. We had written that platform, Class2Go, from the ground up with a small team in a dozen weeks in Fall; in the weeks before the Winter launch we ripped out the whole evaluation system, about one-third of the code, and replaced it with a whole new engine. In both cases most of our code was fresh off the presses.

Those launches were rocky. I'll tell the story of the DB class launch in January. The first thing we do is a "soft launch," where you open the front door and some people find their way in. Those first visits give you a sense of how things will go.  Surprisingly, the servers were a bit busy.  But we wanted to keep going, so we scaled up capacity and moved on.

The thing that drives real traffic is the announcement email. That gets people to the site. The announcements started going out, students started coming in, and the site lit up. We were in hot water. Servers were overloaded, and most surprising, the database was getting hammered. This was scary and unexpected. We control-C'ed the mail job and quickly hacked additional caching into the site.  We had to trickle out announcements over the next twelve hours.  We made it, but it was a long, stressful day.

And then the days/weeks post-launch were spent watching graphs, triaging 500 errors (user-visible "we're sorry" pages), and installing daily hotfixes. But we got through it. The classes were a success and the team was proud.

So, contrast that to today's launch.  Totally different.

Everyone came in early as usual. I bought bagels. We turned on the class (soft-launch) and the servers hardly noticed. We sent the announcement mails, people came and took their pre-course survey and watched the intro video. Hardly any load. This chart shows the average CPU on our four appservers from 8:00 AM PDT / 15:00 UTC until 10:45 AM or so.

launch-app-cpu

Those are happy servers. Other charts we watched (db connections, load, etc.) told the same story. The most impressive thing was not a single user visible error, no 500's!

Those folks at edX made some solid software.  We're happy to be working with a strong group of engineers and a quality product.  We've had our hands on it only since April, and it was released open-source to the world on June 1.  I fully expect a lot of other universities and organizations are going to have a great time running classes on OpenEdX too.

I just turned off half the appservers since we're fine on capacity. Now off to bed with a good feeling.

Comments

Coding on a Flight    Posted:


airplane

I'm surprised that that I like coding on flights. It's surprising because airplanes are generally hostile environments for most things, but I've found it a good place to code.

The obvious reason is the lack of interruptions and distractions. Usualy there is no wifi, or it is too spotty to count on. So no email or IRC or web. While I know that distractions kill flow, I never seem give myself license to unplug in normal life. I'm a manager, and being a manager means being interruptible.

But there's another reason. When I code unplugged, I code differently. I have to be self-sufficient. Instead of just looking things up on StackOverflow, I take 20% more time to figure it out myself. That's much more satisfying! It's just not that hard to rummage through the Django code or try things out in iPython.

Also it just sounds cool to say you coded something up on the flight.

But thre real question is should simulate "airplane mode" when grounded.  Hmm.

Comments

Share