In "
Tips on Writing News Posts, Reviews, Cartoons for TSS," I addressed the format of writing reviews and news posts for TSS. I skipped articles, but that's a separate thread (i.e., for the future.) I'd like to make this the White page to the previous Red, if I can allude to history, by addressing not the physical form, but the intent of writing for TSS.
"How to write" is, and always will be, a challenge, especially for technical people like us. We tend to write because we have to, not because we want to. We work well within syntactic constraints – give us a BNF, or something generated from a BNF, and we're happy.
There are rules in writing, too, though, and since we're rules-oriented, that helps. I'd like to look at another aspect of writing – the rules – so that everyone benefits. As usual, I'm not the be-all and end-all of human communication, so feel free to weigh in.
The first rule in writing is: write. It's not to get your grammer perfectly, or spellling everything right. If you've got something to say, well... saying it is better than not saying it at all. The mechanics of the message can be fixed.
After that, it's all down to writing effectively, making sure that what you want to say is actually being said, and understood. Rules apply here, too, and sometimes they're not obvious until you think about them.
Rule number two: remember the details of what you're writing, and communicate them to your readers. Probably the number one mistake of technical writing is the assumption of familiarity on the part of the reader.
That means that if you're writing about, oh, Hibernate, it's very natural for you to assume your readers know all about Hibernate, except for the parts you're writing about. Even then, writers tend to think that readers understand completely on the first reading, so they give a valid explanation that isn't clear, and then presume that explanation was understood.
No matter how much we wish we could read your mind and acquire your knowledge through osmosis, it's not going to happen.
So assume your readers are smart and that they can think, but that they're complete strangers to what you're writing about. Throw us a bone, in case we're living under a rock and don't know what Hibernate is. Maybe give us a little explanation, once we understand that Hibernate is an O/R mapper, of why what you have to say is relevant – don't assume we understand immediately. Maybe we've never dealt with caching the way you have; maybe we've never seen or thought of the problem.
This is why very little technical writing reaches the audience it should.
Rule number three: readers don't want to read this. I said this in the first article on the subject, but it's worth repeating. Readers don't want to read. They want to know.
Here's the harsh truth: you get one sentence to capture a reader. One. Not three; not two. If your first sentence is a throwaway sentence - “Have you got a bald spot?” - your news post is thrown away, too. This isn't just your readers, this is your Humble Editor, too.
I have to read a lot, and I don't need the burden of having to dig through lots of mush in order to find content. I'm probably more sensitive to this than the other readers are, but at the same time, I'm used to trying to find meat under a pile of grease; most readers typically aren't. If you can't get your message across quickly, that's an extra burden on me to dig out what you meant, to try to see the relevance.
The constant "Your Humble Editor" crap isn't actually crap – I don't consider myself to be smarter or better than my readership is. I'm just blessed to be where I am. If I have to dig out your message for you, chances are good that I will get it wrong.
You don't want that.
So make your sentences count. Tell me something; make it quick; make it understandable. If that first sentence is able to grab a reader, if it's able to communicate why a reader should be interested in reading, you've done a good job. The rest is just backing that first sentence up.
TSS is not, despite what some people say, about flamewars or hit counts. We benefit from those things, I suppose, and there's nothing like a flamewar to drive up hit after hit ad nauseum, for people looking for jabs and insults.
That said, I hate flamewars and trolling for hits is distasteful. I know TSS gets accused of it fairly often, and historically, flamewars were quite normal – but I would like to point out that I've tried very hard, and as subtly as I could, to discourage flamewars in favor of actual content.
Controversy shows up, too, but not for controversy's sake, when I can help it.
Rule number four, then, is "Make your contribution count for something." If you're writing for today, use your blog. If you're writing to improve the community, use TSS.
Again, TSS is
your site. I'm not driving it; I'm also not trying to be a "star" or anything like that. There are plenty of sites out there trying to feed egos. My hope is that my readership is able to see past that, and can appreciate art for expression, not as market campaigns. (Hopefully, it will capture your imaginations.)
Thanks for reading, and I'd love to know what you think about these rules.
