How to write an announcement for your software project

| 1 Comment

In my job as editor of Perlbuzz, I get email all the time asking me to run announcements about all sorts of Perl-related things. They're usually announcements of a new release of some module, or something about an upcoming conference. And usually I don't run them, because they violate the first rule of announcing something:

An announcement that says "PerlWhacker v1.5.3 has been released" is not interesting to anyone but a small handful of people. The most important part of being interesting is that your announcement has to have an angle.

Without an angle, there is no reason for the reader to read past the headline

The angle is the part of the story that says "This is why this is interesting to you, the reader." There has to be a reason that a story is interesting, not simply a recitation of facts. There has to be a hook, a reason for the potential reader to see a headline, or maybe the first paragraph, and say "Huh, I'd like to read that."

Here are some examples.

  • Bad: "Devel::NYTProf version 2.04 got released, here's the change log." No angle, very boring, unlikely the reader will pay any attention to the story, if she even clicks it in her feed reader.
  • OK: "Devel::NYTProf v2.04 got released, and it now uses 90% less disk space by using the Zlib compression library." Sort of interesting, because the reader can say "Huh, that sounds like a cool hack. Still, what's the effect on the reader?
  • Good: "Devel::NYTProf v2.04 got released, and it uses 90% less disk space, because Nicholas Clark was trying to run NYTProf on the entire Perl test suite and ran out of disk space, and he worked with Tim Bunce on a patch." That's an angle because it tells a story that the reader can relate to.
  • Great: "Devel::NYTProf v2.04, and it uses less space, because Nicholas Clark was running the Perl test suite against it, and here's a link to the findings from that research." Bingo!

Assume that the reader knows nothing about what you're announcing.

Finally, you must assume that the reader doesn't know what you're talking about. Most of the announcements I see are announcing to a small group of people who are aware of what is being announced, simply notifying that group that something has happened, excluding the readers not yet in the know.

I'm going to pick on the announcements for Summer of Code, both because they're excellent examples of how to exclude readers, and because I want the GSoC to succeed wildly. That's why I took the time to revamp the announcement when I ran it last night.

The original announcement that Eric Wilhelm ran is this:

The Perl Foundation has been officially accepted into the Google Summer of Code 2009 program as a mentor organization!

Hopefully some of you have identified some potential students already. Now we need your help getting them to submit their proposals.

http://leto.net/dukeleto.pl/2009/03/tpf-accepted-to-google-summer-of-code-2009.html

The student application period begins Monday, March 23rd and runs through April 3rd. (Students note: you can edit your proposal throughout that 11-day period -- getting it started early and talking to potential mentors greatly increases your chances vs throwing it over the wall at the deadline.) See this page for details:

http://code.google.com/soc/

Interested students and potential mentors, please read the GSoC info on the Perl wiki:

http://www.perlfoundation.org/perl5/index.cgi?gsoc http://www.perlfoundation.org/perl5/index.cgi?gsoc_2009_projects

If you're interested in mentoring or have a good project suggestion, now is the time to get your info up on the wiki so students will know about your code and where to find you.

Eric has done a ton of work for GSoC this year and last, and it's safe to say that the Perl involvement GSoC wouldn't be as great, in fact might not even exist, without Eric's work, so this is no knock on Eric. But this announcement has some huge failings, and it leaves questions in the mind of the reader who doesn't know what GSoC is.

  • What is Google Summer of Code?
  • Why is it interesting that TPF is a mentor organization?
  • Why do I care about it?
  • What's in it for me, the reader?
  • What is a student?
  • Why would a student want to join GSoC?
  • What is a mentor?
  • Why would someone want to be a mentor?

In short, Eric wrote the announcement for the people who already know what GSoC is, and excluded the other 90% who don't. Jonathan Leto's announcement has the same failings.

It makes sense why Eric and Jonathan wrote they way they did. They've been busting their asses for weeks (months?) working to set things up. They've been working inside the echo chamber of other people that are involved in the project. The parts of the project in the forefront of their minds are the details like how to sign up and how to write a proposal. However, to someone unfamiliar, it's noise until he knows the overview.

Get people to read your words

Whether it's an announcement of your software, or a resume, or a posting in your blog, you have to give the reader a reason to read what you've written. When writing, we tend to focus on the details of the text, expecting that the reader will consume our every word. Problem is, people aren't like that. We skim. We read titles. If it's not interesting we move on.

In my book on job hunting, I hammer home the idea that without a compelling summary at the top of your resume, the reader is not going to spend much time digging the good stuff out of your bullet points at the bottom. It's the same rule with announcements about your software project.

Next time you're going to announce something, show the announcement to someone who is not involved with the project, maybe a co-worker or your spouse. Ask him or her to explain what you're announcing. Try to understand how your article sounds to someone unfamiliar with it. Your project's success may rely on it.

1 Comment

I think a lot of us in the Perl community lose sight of those outside of our closely-knit circle. Thanks for some great tips on how to reach out to a broader audience!

Leave a comment

Job hunting for programmers


Land the Tech Job You Love, Andy Lester's guide to job hunting for programmers and other technical professionals, is available in PDF, ePub and .mobi formats, all DRM-free, as well as good old-fashioned paper.