What makes a good developerWorks article

Tips from the people who decide what to publish

If you dream of writing an article that influences software developers worldwide, read this brief Q&A to find out what it takes to make your dream come true. Three developerWorks editors, including the two who decide what gets published on the developerWorks Rational website, explain what they look for in proposals and what authors can do to make their articles successful.

Share:

Have you recently solved a technical problem that had frustrated you daily, or figured out how to add something that helped your whole team, or proposed a process that your bosses bragged about to their bosses? That's something that other developers need to hear about, so the developerWorks Rational team will be glad to hear from you.

Check the Resources section here for excellent articles that dig into the details of writing for developerWorks. If you're still in the thinking-about-it stage, read on to learn what the editors look for and get their insider tips.

The decision-makers

Michael O'ConnellMichael O'Connell, Editor-in-Chief and Editorial Director at IBM developerWorks

Sera LewisSera Lewis, Manager, Rational Web Marketing and developerWorks Rational

Robin WoodRobin Wood, Acquisition Editor and Project Manager developerWorks Rational


Q: What do you consider in deciding whether to accept a proposal?

Sera: When assessing content, I look for it to meet two goals. First, that it is something that answers a reader's question or that can help readers solve a problem that they face day to day. A how-to article can be about how to use a tool or how to think about something, not just how to solve a technical problem. So it could be about something as small as tweaking a GUI or as big as redefining the business process of your company.

It needs to be something that makes a reader's life easier. Beyond that, I want it be interesting, so the abstract needs to immediately engage me. If the author can't be interesting in one paragraph, it's unlikely that the full article will be interesting. The abstract should state the problem and state it clearly enough that someone not familiar with the problem can understand at least the scope of it or at least understand it enough to know whether it's related to something they're working on.

What article abstracts should include

Distill the essence of your article to only two to four sentences. Don't just repeat what's in the introduction, and make sure that it covers these three points:

  • What your article is about
  • Why that's important
  • How readers will benefit by doing what your article says

Michael: My mantra has been "relevance." Focus on the wants and needs of the developers and IT professionals, what they value most. Characteristically, that means technical hands-on, how-to content. Tell the reader how to do something and show them with examples. That could be how to craft software, solve technical problems, or improve performance of the software. Even if it's a very short article about a very small piece of the process, if it's a common problem or a critical issue, we need to offer that information to our readers. We want to focus on true real-world issues that people are grappling with, as opposed to hypotheticals. And I agree with Sera: We want to answer questions and help readers solve problems.

Robin: developerWorks Rational uses a proposal rating system that ranks the product, category, topic, alignment with Rational and IBM goals, author's credentials, quality of the abstract, and the estimated time factor to produce the article. Everything's weighted. Based on how the proposal comes in and what I plug into the tool, a number is assigned. And based on that number, if it's in the range to accept, I do.

The content shouldn't be marketing-oriented, and the subject of the article needs to mean something to our audience. We have certain products and categories that get priority at different times. This means that proposals related to those categories are going to rank higher than something that comes in about an older product, such as Rational Purify, for example.


Q: How can authors make their articles more appealing?

When you're ready to write

  • Avoid Introduction and Conclusion as headings. Readers often skip those, and it's obvious that the beginning is the introduction. If you use a Summary section, some will read that and the abstract first to decide whether to read the article, so make sure that both are informative but not the same. It's fine to wrap up with just a couple of sentences or a paragraph, instead. But don't just stop, because it's like ending with a thud.
  • Don't simply repeat the abstract at the beginning of the article. Try to include the keywords in the first paragraph, as long as it's natural, not contrived.
  • Give readers the context in the first paragraph or two, but not the whole history of the topic. Get to the point as quickly as you can.
  • Use active verbs and keywords in headings and subheadings (Example: integrate this, not integrating this). Keep headings and captions to one line.
  • Use examples and illustrations as necessary, including screen captures, tables, or code listings or snippets. If they're not essential for the reader to understand the article, skip them. There's nothing more boring and time-wasting than "Do this (see the Welcome screen in Figure 6), and then do this (see Figure 7)."
  • Pay attention to the structure of your article. Generate a table of contents, and check it to make sure that it flows logically and that the wording of headings is consistent and clear.
  • Include entries for the Resources section that are related to your article. The editors will add the standard ones required for all articles.

Michael: How you position it can often make all the difference. Broader objectives help. For instance, will it interest people who aren't using the product yet or only those who already are? Is it relevant regardless of what software they're using?

Although broader objectives help draw a wider readership, ultimately we want technical how-to content, and that invariably means getting tightly focused so you can discuss technical details and a specific task and show software developers and related IT professionals how to accomplish that task, step by step. If you stay broad, it's hard to provide the technical details that our community often values most.

And of course, accuracy, quality, and clarity are important. If an article contains code that has a bug in it, fragments rather than complete sentences, typos, figures that are flawed, or links that are broken, it hurts the credibility of the article, as well as developerWorks and IBM. Readers will become skeptical and not continue reading.

Finally, make sure that the topic is either timely (focused on today's top topics and emerging technologies) or timeless ("evergreen" issues that remain pertinent over time, such as security or optimization). Also, make sure that the information is up-to-date.

Sera: A successful piece is self-contained. It clearly states the problem, the solution, and the steps between.

Choose topics that are emerging technologies or that we haven't covered as much in articles already in our library. That could be something like a process, such as agile development, or products that are newer in the IBM portfolio, even if they aren't our newest products. For older products, because we already published so much about their features and functions, it would have to be about something exceptional, new, or unique.

Robin: When somebody submits a proposal, it should include a brief paragraph that says what the article is about, information about the author's qualifications, and who the target audience is.

The content and structure both affect my evaluation. If the content is just a list of "do this, do this, do this," I'm not so keen on it. I prefer the articles that say why you're going to do something and then explain how to do it. Screenshots help. They need to be clear, but if they're not needed, don't include them.

Edit yourself "Brevity helps with readability," says Sera. "Our authors need to be capable of telling a story of about 1500 words that can be of benefit." Cutting almost any draft by one-third will make it twice as good. Tighten and trim. And follow the timeworn saying among editors, "Kill your darlings." Meaning: If you think a phrase or tangential bit of information is particularly literary or brilliant, cut it. It will hurt a bit, but you'll feel much better later (and avoid feeling embarrassed).

Q: Do you work with first-time authors?

Sera: You need to be a strong thinker to write a developerWorks article, because you need to articulate complicated concepts in a simple way. But don't let concerns about your writing skill or command of written English hold you back. We have many, many technical authors whose native language isn't English or whose strength is their technical expertise, not their writing. That's why we have editors.

If you are on the edge about submitting an idea, submit it. If we're not interested, we'll say so.

Resources

Learn

  • Read the developerWorks editorial policy, which explains what we publish and what we don't.
  • Study the kinds of articles developerWorks publishes by subscribing to the IBM developerWorks newsletter, a weekly update on the best of developerWorks tutorials, articles, downloads, community activities, webcasts and events.
  • Search the Technical Library in the Rational software area on developerWorks to see what we've already published that's related to the article that you plan to propose. You might want to include links to related articles in the Resources section of your article.
  • Check to see what currently ranks high on the editors' content wish list. Just because your idea isn't there doesn't mean that they won't be interested, however.
  • Submit a proposal first, and don't start writing until you get the go-ahead.
  • Be sure to read the instructions on these pages before you start writing:

Discuss

  • Share your knowledge and help others who use Rational software by writing a developerWorks article. You'll get worldwide exposure, RSS syndication, a byline and a bio, and the benefit of professional editing and production on the developerWorks Rational website.
  • Follow Rational software on Facebook and Twitter (@ibmrational), and add your comments and requests.
  • Ask and answer questions and increase your expertise when you get involved in the Rational forums, cafés, and wikis.
  • Connect with others who share your interests by joining the developerWorks community and responding to the developer-driven blogs.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=646032
ArticleTitle=What makes a good developerWorks article
publish-date=04082011