How to write a bad abstract

Ironically, the only talk that disappointed me at all at CodeMash was... mine. I thought my delivery was a little rough - pretty much because it's a really bad time of year for me to practice a talk.

I had a (great, attentive, but) smallish audience, too. One of the reasons was simple scheduling - there were some amazing talks opposite me. I was tempted to slip out and watch one myself! The biggest problem, though, was me. I wrote a bad title and abstract for the program guide.

reStructuredText: Plain Text Gets Superpowers
Technology/Platform: Python
Difficulty Level: Beginner

Abstract: Write a document, just once, in plain text. Enjoy all plain text's benefits - speed, simplicity, scriptability, version control. Now, from this single plain text source, automatically generate beautifully-formatted webpages, presentations, .PDFs, auto-indexed documentation trees, and more. It's time to quit slacking on documenting your software. reStructuredText will make you actually enjoy writing docs!

What's wrong with this? It's a nice narrative that fits together and builds to a nice little conclusion... but it's bad for a program guide.

I assumed attendees would read the whole abstract carefully. Then, when I got to CodeMash, what did I do to select sessions I would attend? I quickly scanned over the list of titles, and based on that, hastily read some of the abstracts. I forgot that geeks are pressed for time, especially at conferences!

There were three important messages for attendees to know to decide whether to come:

1. This is a talk about writing documentation
2. It is independent of what programming language you use
3. This talk provides a helpful tool (i.e., it's not just a preachy sermon)

You have to read all the way to the end of my abstract to get messages #1 and #3, and #2 is never communicated clearly at all. So, what would a good title and abstract have looked like?

Your Docs Won't Suck Anymore
Technology/Platform: Other *
Difficulty Level: Beginner

Abstract: No matter what programming language you write in, it's the English language that's killing you - your lack of good documentation is driving potential users away. reStructuredText is a technology and a family of tools that will make writing documentation easy, powerful, and satisfying. We'll introduce reStructuredText and get you started on writing beautiful documentation for any program or language.

* - "platform-independent" would have been the best choice for "Technology", but it wasn't in the dropdown. I worried that choosing "Other" would imply reST was implemented in Scala or something. I should have done it anyway, though, because most CodeMash attendees don't know Python and probably read "Python" as "not for me".

The take-home lesson here: when writing titles and abstracts, be very mindful of the divided and rushed attention of the typical geek. Don't be coy and save the good stuff for the fine print. Get your message across up front.

Fear is not a virtue

I know there have been a million news items like this, but this is the one that puts me over the edge.

SAN DIEGO — Students were evacuated from Millennial Tech Magnet Middle School in the Chollas View neighborhood Friday afternoon after an 11-year-old student brought a personal science project that he had been making at home to school, authorities said.

Maurice Luque, spokesman for the San Diego Fire-Rescue Department, said the student had been making the device in his home garage. A vice principal saw the student showing it to other students at school about 11:40 a.m. Friday and was concerned that it might be harmful, and San Diego police were notified.

The school, which has about 440 students in grades 6 to 8 and emphasizes technology skills, was initially put on lockdown while authorities responded.

Luque said the project was made of an empty half-liter Gatorade bottle with some wires and other electrical components attached. There was no substance inside.
...
Luque said the project was intended to be a type of motion-detector device.
...
Both the student and his parents were "very cooperative" with authorities, Luque said. He said fire officials also went to the student's home and checked the garage to make sure items there were neither harmful nor explosive.

"There was nothing hazardous at the house," Luque said.

The student will not be prosecuted, but authorities were recommending that he and his parents get counseling, the spokesman said. The student violated school policies, but there was no criminal intent, Luque said.

I finally understand Al-Qaeda's master plan, and it's freaking brilliant. Resenting American technological dominance, they have found a way to end it, convincing us to semi-criminalize technical curiosity and thus lobotomize our culture. I'm just surprised that we're choosing to participate in the plan. I thought we were on opposite sides?...

Is there a political movement or group I can join to fight this? Common-sense people grousing about how stupid each incident is is failing to hold back the tide. Something vaguely like the EFF but with a broader scope - because all science and technology is under attack now.

Fear is not patriotic. Fear is not a public service. Fear is not a virtue.

MongoDB

Gloria Jacobs told me about MongoDB at PyOhio, but I was too busy conference-chairing to see her talk, and time has flown by. Her enthusiasm prompted me to see Mike Dirolf's MongoDB talk at CodeMash, though, and wow. Thanks, Gloria and Mike! I like it, I really like it!

My frustrating experience with BigTable had given me a "Bah, humbug!" attitude toward the NoSQL fad, but it really looks like MongoDB is the cure for that. It surrenders much less query capability than the other NoSQL contenders do. The simplest of those are useful only if you already have the key for your desired record in hand, and BigTable's limitations make it feel only moderately better to me. But MongoDB's query capabilities are really rich, good enough for many (though of course not all) real query needs.

Now, don't get me wrong; there are a *whole lot* of tasks for which an RDMBS is still very much the answer. When you need transactions, or child items that aren't tucked neatly under single parents, or complex queries - and how often do you really *know* that you'll never need complex queries? - it's safer to use an RDMBS.

I think that, when the database is an enduring construct, important in itself - when multiple applications may be written against it, and new applications yet unforeseen may appear in the future - then a good RDBMS is the only way to go. In such cases, it's just impossible to safely predict what you'll need to do with the data one day, so you need database software that can do virtually anything.

But when the database will play a supporting role to a single, well-defined application, and will not outlive the application. then a non-relational database could be very convenient, and MongoDB looks to me like a fantastic choice.

Let's call this Devlin's Doggy Directive of Databases:

If the application is the dog, and the database is the tail, consider a non-relational database.
If the database is the dog, and the application is the tail, stick with a relational database.

If you doubt that I'm qualified to go naming rules of thumb after myself, let me remind you that have ten years of relational database experience, a sparse smattering of non-relational experience along the way, and that my parents owned a boarding kennel when I was young.

CodeMash general recap

Believe the hype. CodeMash is all that. It's people from all over the region and beyond whose enthusiasm and intelligence is too much to stay channelled in one technology. There are consistent preferences - for agile methods, open-source code, etc. - and a majority user community - .NET - but it's full of people who know that cross-pollination and cross-training are where it's at.

The one problem is the same one that all big conferences have: the scheduled talk track is so rich that it's almost impossible to pull yourself away to the Open Spaces. As next year's planning begins, I'll agitate for a schedule that somehow makes some Open Space time that doesn't run parallel to sponsored talks; I actually think Open Spaces on the precompiler day (maybe as the entire content of the precompiler day) would be a great idea. Except that it's probably best to let the regular conference content prime the pump first... hmm...

reStructuredText talk follow-up

Thanks to everybody who saw my reStructuredText talk at CodeMash 2010! My slides are at the end of catherinedevlin.pythoneers.com. Those who asked questions I couldn't answer - thank you! I'll be researching the ones I remember so that I can post on them; commenting or emailing me reminders of your questions - or new ones - would be much appreciated.

I had a great time at CodeMash; the organizers deserve a huge round of applause. I'll post more extensively with some of what I learned... after catching up on sleep.

Codemash - day 0 (precompiler) report

A good start to CodeMash. I started with a session on the Ruby Koans, a very nice way of teaching; it tempts me to join the crew building a corresponding set of Python Koans. In fact, it would be really interesting to host Python Koans on Google App Engine... Hmm...

Next I went to Mary Poppendieck's session on leadership in software; alas, for me, it was as much frustrating as inspiring. She described techniques proven to produce good software consistently, and I see very few of them in use in the Air Force. Worse, the Air Force is driving hard to make the problem worse: centralizing, centralizing, centralizing - building up the separation between decisionmakers and IT professionals and IT users with thicker and thicker walls made of miles, layers of management, internal organziational boundaries, and government:contractor barriers. *sigh*

She did, however, make me realize that my employer - a small contractor that sends IT professionals in ones and twos to work on projects as our customers need - can do a lot more to improve skills among our employees. We could get together occasionally from our various customer sites to work together on our skills, or at least have a mailing list for technical chat among our employees.

But here's a question - from a purely selfish point of view, is this the right way to spend my energy? After all, there are already plenty of groups of professionals dedicated to mutual skill improvement. They're called user groups, and the time I spent on internal skill development could just as well be spent deepening my involvement in local user groups; the payoff may be bigger, because I'd be involved with a self-selecting group, with people who already believe it's worth going out of their way to hone their own skills and others'. User group members have an attitude, a hunger and thirst and personal committment to excellence, and trying to create that attitude among my company coworkers may be a lot less fruitful than taking advantage of people who alreay have it.

Your thoughts?

Anyway, today begins CodeMash in earnest, and I'm loving it. Most of all, I like meeting up with old friends and meeting new ones. Geeks - particularly geeks who are active in the user community - are just fun, interesting people to be around!

PyCon early-bird deadline TOMORROW

Time to register. Srsly.