The tradition of freshmeat editorials has been sadly neglected this year. We're going to remedy this by posting an editorial every week from now on, and we invite you to write on any software-related topic about which you have opinions to share. This week, I'll kick things off by offering one myself about how to write a great freshmeat submission and how to write great documentation generally. At the bottom of it, you'll find instructions telling you how you can be our next writer and earn a freshmeat t-shirt and 15 minutes of fame.

"All through The Elements of Style, one finds evidence of the author's deep sympathy for the reader. Will felt that the reader was in serious trouble most of the time, a man floundering in a swamp, and that it was the duty of anyone attempting to write English to drain this swamp quickly and get his man up on dry ground or at least throw him a rope."
-- E.B. White

This quote comes from the introduction of the best book on writing in English, Strunk and White's The Elements of Style. White first encountered The Elements 80 years ago and was, of course, thinking about writing that would appear on paper. Today, the situation is even more desperate. Most freshmeat readers spend all their days online. We read newsgroups, we read slashdot, we read email, we read technical papers, we read documentation, and we read code. We all have tired eyes and tired heads to go along with them.

By the time we come to freshmeat, we're worn out. Any text that doesn't make immediate sense kicks us when we're down. Phrases that make our eyes backtrack over and over to drag out their meaning are more than we can bear. This is why people who go through the freshmeat boot camp to join the news/announcements staff get "Simplify, simplify, simplify!" pounded into their heads. Dozens of updates and new items appear on freshmeat every day. We have to make sure they all flow across the reader's eyes as easily as possible.

Why this matters to you

Massaging the submissions into shape is, of course, our problem. But I have two good reasons for making it your problem also:

1. We regularly get mail that says, "I submitted my software last night and I still don't see it this morning. What's going on?" Sometimes the delay is out of your control, but sometimes it's caused by the "ick" factor which I describe below and about which you can actually do something.
2. By adopting some of the points I make here in your documentation and the Web pages of your projects, you might get more people to use your software. You can generalize this editorial and look at it as advice for avoiding the truism "Good hackers don't write good documentation".

The first point can be addressed with statements of fact; my response to the second will be filled with my opinions. First, the facts:

How to get your software on freshmeat ASAP

We do our best to get everything onto freshmeat as soon as possible after it comes in. Sometimes, stuff happens over which neither you nor we have any control. At other times, your software would have gone up right away if it hadn't been for the "ick" factor.

The "ick" factor

Even the members of the freshmeat staff are only human. There are times when it's late, late, late at night and one of us has been pounding through submissions for a couple of hours and is just about to finish when he lands on a submission so hideous that all he can do is scream "ick!", run away, and leave it for the person on the next shift.

If your submission gets to us at one of these times and you've prepared it so it's a no-brainer, our bleary-eyed staff member just clicks "go", and you're on. If instead you've offered an "ick" submission, you can be left hanging until someone with a sufficient caffeine-to-blood ratio comes along to take care of you.

So how do you make your submission a no-brainer? Here are a few ideas:

1. Don't write the Great American Novel

The number one problem which will make a staff member cower in terror is a description or changes list with a thousand words in it. We like to give you enough room to say what you need to say, but we also need to fit everyone onto our front page each day, and can't let you take over the entire space. Your submission should fit in the box we give you for it. If it doesn't, we'll make it fit.

Making it fit requires time and care, as we have to try to delete enough to cut it down to size while not destroying your message. We have to rearrange things and make judgments about what's most important and try to move it to the top. Since this takes time and a little thought, our night owl worker is just going to pass on to something easier and quicker.

Be succinct and clear. Not only will your announcement appear much more quickly, you'll be the one to decide what to include instead of us!

2. Don't use HTML

freshmeat's content doesn't just appear on the Web page. It gets sent out each night in the plain text newsletter and is placed on the backend for the use of people who aren't expecting to find HTML in it. If you include HTML, we have to go through and cut it out. If you've used a lot of HTML with unordered lists and such, your submission may look scary indeed.

3. Verify your links!

We can't announce version 3.2 of your software if you forgot to put it on the server, forgot to set the permissions on it, or just gave us a bogus URL. Your announcement is going to sit there until you or we can fix it.

A special case of this involves Metalab (the repository formerly known as Sunsite). Lots of people submit announcements with the URL of where the software will be on Metalab when it arrives there. Unless there's another URL for it, we can't announce it, because people won't be able to get it. Metalab is nice enough to send you mail when your package is available on their servers. Wait until then to submit the link.

And when you change the version number of your software, don't forget to submit a change request for the download URL too! Otherwise, we have to hunt down the URL and submit the change ourselves.

4. Talk in the third person

Consider this list of changes:

I reordered the menus, I added support for PNGs, and I changed the configuration file format.

This is fine on your Web page, but who is "I" on freshmeat? The author of the page -- scoop! scoop didn't do any of these things, so write it instead as:

The menus have been reordered, support for PNGs has been added, and the configuration file format has changed.

A long list of changes written in the first person has to be carefully changed, and slows your submission's progress.

5. Make an announcement!

Along the lines of "Are you sure your computer is plugged in?"...

Don't forget that you have to submit an announcement for your software after you submit its appindex entry! When you add a new piece of software to our database, you have to also submit an announcement or it will never appear on the front page. Yes, this is explained during the submission process, but lots of people still forget it and write to ask why they never saw their software appear.

Three extras

While I'm on the subject, I can't help adding three extra suggestions that don't effect how quickly your submission will appear but which will cause you extra work if you ignore them, because what you type will just be deleted.

1. Drop the marketspeak

How many Pointy-Haired Bosses do you know who read freshmeat? I don't know any either, so know your audience and drop the marketspeak.

Here's a real life freshmeat software submission (with the product name changed to protect the guilty):

foobar provides the ability to allow people to use the mail, scheduling and time-management functions so often used in the enterprise while insuring the cross platform capability not found in any other product in today's market. foobar represents a suite of applications. On the client side is provided an internet email application. That application is then taken a few steps further by adding calendar functions, contact management, scheduling and eventually enterprise workgroup tools. Currently, foobar is in Peer Review Release 1 which is essentially an email client that will allow users to glimpse the functionality of what the final product for commercial release, (Release 4), will be like.

Here's what was left after I was done with it:

foobar is an Internet email application which provides calendar, contact management, scheduling, and time management functions. It is currently under development, and only a small part of its functionality is in place.

The authors can update it when/if all their other plans come to fruition.

You know you're going wrong if you find yourself using phrases like:

• "best in its class"
• "enterprise-ready"
• "used by 12.38 percent of the Fortune 500"
• "capabilities not found in any other product in today's market"
• "a strategic component of impactful ebusiness"

The average freshmeat reader will be repelled by this kind of talk, not attracted. Talk about what your software does, not about how great it is. Your users will judge its quality for themselves.

(Open Source authors can be just as guilty of this as commercial ones, BTW. It's just as bad to say "Mine is the best GPLed IRC client that exists or ever will exist! No one can touch me! All the others suck! I'm l33t, d00dz!!!")

2. Don't thank the academy

We're glad to hear that you're getting lots of help with your Open Source project, but we don't need the names, email addresses, and URLs of everyone who's helped you. We get submissions with passages like:

Added XML support thanks to Bill Schaeffer (bill@schaeffer.org). Fixed the FreeBSD compile errors (thanks, Phreaker! ). Borrowed some parsing ideas from the cool guys at the Apache project (http://www.apache.org/).

Anyone who's interested in your software will follow the link to your homepage, and you can give credit where it's due there.

3. Don't submit more than once a day

Unless there's an exceptionally good reason, we don't like to announce two versions of the same software on the same day. We're not even very happy about announcing new releases of the same software two or three days in a row. Once-a-day releases draw attention to themselves at the expense of other people's work.

How to Write Good

Ok, there's the facts; now on to the opinions. Most of the above is freshmeat-specific. What follows is also useful for your interactions with freshmeat, but could equally apply to your README or your software's Web page. If you can make them easier to read and understand, more people are likely to stop and give your software a try.

Good hackers don't write good documentation

There's no reason this has to be true. Everyone should have the ability to write well; it's a basic skill of a well-rounded person. If your education failed you (or you failed it), you can still teach yourself to explain your ideas simply and logically in writing. Go to the library and pick up a copy of the Bible of writing in English, The Elements of Style by William Strunk, Jr. and E.B. White. Learn to spell, learn to punctuate, learn to edit. You'll be doing a favor to tired eyeballs everywhere.

If English isn't your first language, it may not be your favorite and you may sharply feel its deficiencies when you compare it to your native tongue, but it's what we're stuck with, and it's worth your time to learn it well so people can understand you. Sometimes when I edit the writing of people who are pushing hard against a language barrier, I just have to cross my fingers and hope I'm conveying their intentions.

What if you really, truly cannot spell or organize a coherent paragraph to save your life (it can happen to the best of us)? Find one of your software's users who can write well and ask him whether he would be willing to be your press agent. You could hand over to him the care and tending of your documentation, your Web page, and your freshmeat submissions. Wouldn't you rather be coding, anyway? More people than you might think would be willing to do this as a thank-you for the software you've given them. If you don't have anyone handy to help you out, try The Open Source Writers Group; they may be able to match you with someone.

Don't be l33t.

l33t d00d talk makes people think you're 10 years old and doesn't encourage them to download your software. It will be wiped from your freshmeat submissions, and you'd do well to keep it off your Web page unless it's used ironically.

Talk about what your software does today.

Talk more about what your software does than about what it will do. Submissions come in from time-to-time which say, "Right now, it prints 'Hello, world!', but someday, it will be an air traffic control system."

An example

I'll close with a fictitious but representative example I made up to use in training a couple of the freshmeat staff.

The original:

fixed bugs in config file format submitted by Ethan Fubalt (thanks, Ethan!); runs much faster now; popup problem fix; some people think you can exploit the showfile() function to read files with 600, but I fixed it; thinking of switching to libshoe to clean up the dirty feet problem; now asking for a password each time you log in not just the first; prompts for the group to add a user to now; doc updates thanks to the guys at linuxxunil.com; new icons are in the tarball; new modules for ssl and libpng; you should really upgrade because its really cool now; fixed a bug in cookies and one that kept it from compiling under cp/m; doesn't segfault when you make two connections at once now; might get 1.0 out before i die...; and stuff.

My final version:

Security fixes for the showfile() function (which let users read files for which they didn't have read permission) and for the password challenge, which was only made on the first login. Bugfixes related to the config file format, the popup problem, cookies, cp/m compilation, and segfaults which occurred when two simultaneous connections were made. New features, including speed improvements, a prompt asking to which group a user should be added, doc updates, new icons, and new modules for ssl and libpng.

I'll spare you my analysis of how I got from the one to the other, but notice how much easier it is to read the second. I'm not even making a real paragraph here; it's three clauses without verbs made to look like sentences. The difference is that they're clearly structured now. You can tell where the three ideas (security issues, bugfixes, and new features) begin and end, and what's important. The original is impenetrable to anyone except those who take the time and effort to sort out what's important in it, and freshmeat readers don't have time for that; they have 50 more announcements to read. Visitors to your Web site don't have time for it either; there are lots more pages to visit and lots more software to try. Explain yourself well and explain yourself quickly, or they'll just click off to the next page.

It takes a little thought to express yourself clearly, but your users will thank you, and so will we. :)

---

Jeff Covey received his degree in classical guitar performance but spent so much time with his computer that he fell in with a bad crowd and ended up working for Andover.net. He currently works on freshmeat and runs a computer lab for the kids in his neighborhood in his spare time.
http://pobox.com/~jeff.covey
jeff.covey@freshmeat.net

---

T-Shirts and Fame!

We're eager to find people interested in writing editorials on software-related topics. We're flexible on length, style, and topic, so long as you know what you're talking about and back up your opinions with facts. Anyone who writes an editorial gets a freshmeat t-shirt from ThinkGeek in addition to 15 minutes of fame. If you think you'd like to try your hand at it, let jeff.covey@freshmeat.net know what you'd like to write about.