Tips for writing articles
We regularly get article submissions that are good, but they're not ready for prime time. Sometimes, we can assign an editor to salvage the article, but it's always better to have the author fix it up himself or herself. Besides saving us time, it also helps train the writer on how to write better and not only is that beneficial to our readers, but it's good for the writer's personal and career growth.
What we're including below are snippets of emails we've sent to authors. Reading through them, you'll get a good idea of what you should think about.
By the way, if you recognize correspondence about your article in here, don't take it negatively. We're not including names or specific article references and usually, we'll have published your article because you'll have shown considerable improvement.
Write as if you're a friendly teacher
Writing an article is quite different from writing a set of instructions or a user manual. Although real people need to read all three, somehow it seems ok to forget that the reader is a person when you’re writing a tight set of steps.
But when you’re writing an article, especially one for a ZATZ publication, you’re having a conversation with the reader. Thousands upon thousands of flesh-and-blood people read each of our publications. When they read an article, they’re connecting with the author in a very personal, individual way.
Think about your favorite magazines. You may not know all the authors, but you do get to know, sometimes even feel you really know, the regular contributors. Regular readers have had to listen to me go on about my cat, my broken arm, my move, my dreams for the company, my friends. They’ve even been witness to my frustrations and my rather weird sense of humor. As a result, many of our regular readers feel a connection to me and, from my writing, they can tell I feel a connection to them.
So as you write your article, I want you to keep two pictures in mind. The first is of someone being handed a list of steps or instructions and being told, “Good luck kid. Let me know how it turns out.” That’s not the approach I want you to take when writing an article.
The second picture to keep in mind is that of a wise and friendly teacher, putting his arm around your shoulder and saying, “Hey, I can help you with that. Let me show you how.”
When you’re writing an article, you’re that wise and friendly teacher.
Many of our writers come from a technical background. In engineering school (or other academic variants), we were taught to write cold, emotionless academic papers. The more precise-sounding (and, frankly, dull), the more important the paper seemed and the more intelligent the writer was supposed to look. Writing was all about prestige and the geekier, the better.
But when you’re writing for ZATZ, you’re not out to prove anything. People are reading your articles because they’re expecting you to be an expert. You don’t have to be dull to be perceived as knowledgeable.
In fact, many, many of the letters we get tell us how approachable and understandable our articles are. Readers want to learn, not go to sleep.
So, let’s go back to imagining our wise and friendly teacher. And now, imagine you’re the student. Your teacher makes things easy to understand, is friendly, and even has a sense of humor. Your teacher is also warm and can see when you get confused.
Wouldn’t it suck if your friendly teacher suddenly looked at you, saw you were confused, and simply said you weren’t smart enough to understand? Of course it would.
Let’s assume you’re explaining something pretty technical that requires pre-requisite knowledge. If you’re the wise and friendly teacher, you might take one of two approaches. Either you’d tell your student that the knowledge required is so much that he’s just not ready right now, but here’s where to go to learn. Or, if a short background will fill in the blanks, you’d provide the short background.
You can apply this in your writing. If you’re writing an intensely technical article that may only be understood by a smaller group, let the reader know that. For example, you might say, “To get the most out of this article, you should understand how the fringlesnoggle works. For those of you who don’t, you’re welcome to read on but you might be a bit confused. If you’d like to learn more, there are some resources at the end of this article.”
Or, let’s assume that the fringlesnoggle’s pretty easy to understand. Then you might say something like “I know I’ve mentioned the fringlesnoggle and it may be unclear to some of you what that is. A fringlesnoggle is like a left-handed wind shifter, except it shifts wind to the right. There’s more detailed information at the end of this article.”
You can almost feel your teacher’s comforting arm on your shoulder.
Articles are more than a list of steps
I want to thank you for your efforts in writing your article. I think it has the makings of an article, but isn't quite there yet. As it stands, it's much more of a set of instructions than an article. If you think about the articles you're likely to read in your favorite magazines, there are nice expository paragraphs, warm transitions, and clear details.
Using an analogy, what you've got is the spine or the skeleton of an article: a list of steps. But you need to flesh out the details. All articles need nice introductions that set the stage and context. For example, what is the problem you're solving? (In this case, you're obviously the expert on your device, so you're able to provide the best troubleshooting guidance.) Then you need to walk through the steps, showing screen shots (these should be provided as .GIF images that are separate files). Finally, and for each section, you need to provide conclusions, transitions, bridges, and a way to better understand the context.
Here's an example. In one of your steps, you say "Note: see below if eth0 isn't listed." Instead, you might say, "To set this up, you'll need a device called eth0. If you can't find that device, it most probably needs to be installed. What follows are the instructions for installing a new Ethernet device. On the other hand, if your device is where you expect it, you can skip the next section." Then you'd create a section called, "How to install an Ethernet device" and provide more specific details.
Also, your title seems to be too broad for the topic. Either expand the article to describe more devices and how to approach it or specifically describe it as how to troubleshoot your own device. I'd MUCH prefer to see an article that's broad and applicable to a much wider audience.
Some other notes:
- You use a ton of acronymns. We explain or expand all of them so you'll need to do so for anything that's a buzzword or acronym.
- Be sure to provide the correct spelling/capitalizations (Ethernet, for example, is capitalized).
- Don't use bold, italics, or other styles. We don't put them in the magazine.
- All of our articles include a product availability section with links. Check them out and include the same for your article.
Some of our best technical articles are written by DominoPower Magazine's Senior Technical Editor Dan Velasco. If you want to see a technical article that's warm and friendly, check out Dan's articles at:
http://www.zatz.com/authors/authorpages/danvelasco.html
Take care, and I can't wait to read the full article!
Articles aren't scientific or academic papers
I just finished editing your article. I've been told that you'd like to continue to contribute to DominoPower, and I'd like to encourage that.
However, dude, you have to lighten up a bit in your writing. You come to writing like I did, from the precise world of engineering and scientific documentation. What you submitted is clearly an excellent scientific paper. Unfortunately, even those of us perverse enough to enjoy reading scientific papers get a bit worn by the dry style.
For ZATZ publications, we go for a warm, approachable style. Great examples of that can be found in Dan Velasco's articles. He's got a great wit, very good writing style, but still gets the technical meat across.
Now, the subject of automated classification is something that's bound to interest a segment of our readers. I personally enjoyed learning more. And since it's a very jargon-specific domain, the article is bound to be more dry than your typical LotusSphere party report. But even in this type of article, there are ways to lighten up. I've taken the liberty of copying out some of your sentences and showing you how you might make them more, ah, approachable.
Before you read them, again, let me be clear I'd like you to write for us. Don't take any of this as a mark against your professionalism. Instead, realize that more people are likely to read and stick with your stuff if they can digest it without indigestion. Ready? Here goes... (one note before we do... I've capitalized some words so you see them as substituted. I don't mean that you should use all capitals in words in your article unless appropriate).
Yours: Another issue to consider is that neural networks deliver only one taxonomic view of the data they're classifying.
BETTER ==> "Another issue to consider is that neural networks deliver only one SET of the CATEGORIES of data they're classifying." It may be more precise to speak of taxonomic views, but people will understand the concept of categories much more easily. That one sentence, alone, will drop hundreds of readers into a Rip Van Winklesque hibernation of nearly epic proportions.
Alternately, you could have defined taxonomy very carefully, but with some humor at the beginning of the article. For example, "No, 'taxonomy' and 'taxidermy' aren't the same thing. Throughout this article, I'm going to use the words 'taxonomy' and 'taxonomic.' Although they're certainly not the easiest words to get your arms around, they're much more precise when talking about classification systems than the term 'category.' But, if it's easier to handle, whenever you see the word 'taxonomy,' substitute 'category' in your head." In fact, I chose to put this at the beginning of the article.
Yours: This can break your concentration when in the discovery mode, often resulting in you losing your train of thought.
BETTER ==> "This can break your concentration when LOOKING SOMETHING UP, often resulting in you losing your train of thought." Discovery mode is technically accurate, but people don't go into discovery mode when looking for sports scores on Yahoo. They look them up.
Yours: Hyperlinked classification taxonomies facilitate discovery
BETTER ==> Argh! My head feels like it's going to explode!! Try: "Hyperlinked groupings make finding things easier"
Yours: based on the significance of aggregate node values
BETTER ==> "based on the significance of THE COMBINED DATA"
Yours: This permits you to drill into the core of detailed aggregations in and across hierarchies
BETTER ==> "This permits you to drill into the core of detailed GROUPINGS in and across hierarchies"
Yours: Managers can also be notified when collaborative profile patterns reach an aggregate point of significance.
Yours: Adaptive classification taxonomies harness infoglut for a world in transition
BETTER ==> I can't believe that was just a headline. Yowzah! Uh, let's try "Manage infoglut". Much shorter, easier to understand. Or "Combat infoglut". Or "Gut that infoglut".
Here are a few you wrote that are excellent:
"...a rich knowledge fabric." It's visual and sensual. You get the idea of what this rich fabric might be, but it's all information. Wonderful imagery.
"They also provide an excellent learning simulation environment since best practice rules can be played forward (What If?...What Is?...What Else?) or backward (Why?), emulating inductive and deductive reasoning, using controls much like a standard television VCR." I like the visuals here. It's a little heavy, but made much more clear with the words and the analogy. Good.
Anyway, I think you see where I'm going with this stuff. Keep writing, but make it warmer and less pedantic.
Chill, dude!
|
