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.