Tips to help you get published on developerWorks

So, you want to write some articles?

IBM® developerWorks® provides an opportunity for you to illustrate your expertise by writing technical articles and tutorials for a worldwide audience of developers, consultants, partners, and customers. Here are some things to know that can better your chances of getting that article you've been working on finally published.

Scott Shekerow, Content Editor, IBM developerWorks WebSphere, IBM

Scott Shekerow is a Content Acquisition and Web Editor in IBM developerWorks, and is the editor of the IBM WebSphere Developer Technical Journal.



January 2009 (First published 28 December 2007)

Introduction

We are pleased that you’re interested in contributing to IBM developerWorks. The knowledge, ideas, and experience of software professionals like yourself -- and your willingness to share them with our worldwide audience of developers, consultants, business partners, and customers -- are important reasons why developerWorks is the premier technical resource for tools, code, and education on IBM software products and open standards technology.

How developerWorks is organized
The editorial content on the developerWorks Web site is organized by zones, differentiated by technologies and IBM software brands. Although all areas work closely together, the editorial staff for each zone operates under a structure that best suits that zone. Therefore, although much of the information in this article is broadly applicable to technical writing in general, this information is specifically intended for authors who wish to submit material for publication in developerWorks WebSphere®.

Several resources are available that describe the developerWorks publishing process in detail and offer guidance on the mechanics of creating technical content for us. You should review that material before you get too deep into writing (see Resources). To help you further, this article provides information to help you better understand a little more about what we do (and why we do it), plus some tips you can use to improve your article and its potential for being published on developerWorks.

If you have thought at all about writing for developerWorks -- for that matter, even if you have already submitted a proposal or published with us in the past, you probably have some questions. Many of those questions are answered here, along with others that you might not have asked, but should. Hopefully, this information will help clarify what you need to do to make your article the best it can be and suitable for the developerWorks audience.


What do you want to write?

You might already have a topic in mind, or you might only know that writing technical articles is something you want to do at some point. Either way, before you start writing anything, it’s important that you know the answers to these questions:

  • What is your topic?
    Choose an area of expertise that you are confident enough to write about. Do not assume that everyone who reads your article will be a novice.

  • Why do you want to write this?
    It’s important for you to know the origin of your article so that your work will have a definite focus. For example, did you decide to write your article because you:

    • Discovered an efficient way to perform an arduous task?
    • Found a new use for an existing product or feature?
    • Want to help others use an undocumented function?
    • Want to share a workaround for a known problem?

    Also, keep in mind that we will specifically ask you about the origination of your article so we can determine any related legal and compensatory issues.

  • Has your topic been covered elsewhere?
    Do your research. Be sure to check product documentation, IBM Redbooks, other developerWorks articles, articles in other publications, other Web resources, and so on. If your subject has already been sufficiently addressed elsewhere, we might decide not to publish more on the same subject. On the other hand, if the existing information is lacking in some way, or if your article is substantially different or includes significant added value, be sure to tell us.

  • Does this content belong in developerWorks?
    If your article is intended to fill an information gap, as in the case of a temporary workaround, the subject might be better served if you submitted your proposal to IBM Support (for troubleshooting) or Information Development (for documentation).

  • How will you approach the topic?
    There are probably infinite ways to write about something, so it will help you to decide the audience and technical depth you plan to address. For example, are you considering:

    • For newcomers: An overview of a product or feature?
    • For troubleshooters: A specific solution to a specific problem?
    • For advanced practitioners: A detailed guide to achieve a specific objective?
    • For decision makers: A broad discussion of technical concepts or standards?
  • What type of content do you want to create?
    What format best suits your topic and approach:

    • Technical article
      Technical articles make up the majority of our site content. Depending on your objective and the information requirements of the topic, a technical article generally falls in the 5-20 page range. Technical articles have a flexible format with which you can present almost any type of information you need to, whether it be a conceptual discussion or a specific technical solution, examples with sample code, an industry case study, performance comparisons, and so on.

    • Tutorial
      If your topic lends itself to a description of explicit steps that culminates in the completion of a discrete task or other tangible objective, then consider creating a tutorial rather than a technical article. A tutorial is essentially an article in step-by-step format, divided into sections that, when followed, enables the reader to accomplish a specific goal, such as create and run a sample application that demonstrates the subject of the article. Tutorials can be lengthy, but their unique format enables readers to complete logical segments at their convenience, and ultimately achieve an educational objective.

    • Technical tip
      A short technical article of about 5 pages or less that simply explains a concise but useful nugget of information with broad applicability.

    • White paper
      Authoritative in nature, white papers on developerWorks can present conceptual discussions on new technology, research results, and nearly anything in between. These formal papers are generally published in PDF format.

    • Article series
      If you are planning a particularly complex article, it might be more usable if it is presented as a series of articles, each addressing a major component of a larger solution. If your technical article is particularly lengthy, we might make an editorial decision to publish it in several installments to better suit the topic or our schedule.

    • Editorial
      Columns are informal opinion pieces authored by recognized technical experts, discussing new technologies or products, trends in the industry, or some other topic-of-the-moment of general interest. Usually 3-8 pages, columns by rotating authors are featured regularly in the IBM WebSphere Developer Technical Journal.


What do we look for?

Topics that are interesting to us are the ones that are interesting to you. After all, you are an important member of our audience, and if you believe there is a need for your article, chances are that others will feel the same way. However, because the volume of submissions we receive and the scope of products we need to cover have grown, it is necessary for us to evaluate article proposals based on the compelling nature of their abstracts along with our publishing capacity. This means that we must often favor the best articles that require the least amount of editorial attention. Here are some ways you can strengthen your submission:

  • In your proposal

    • Grab our attention with your abstract.
      Give your article a great title and explain the objective of your article as succinctly as you can. Use the abstract to promote your idea and to demonstrate your writing. You could have a great idea, but an uninteresting or poorly written abstract presumes an uninteresting or poorly written article. That doesn’t mean that you need to be an outstanding writer, but you do need to be able to communicate your ideas and objectives clearly, and your abstract needs to show this.

    • Explain what's special about YOUR article.
      Describe WHO your article is intended for, WHAT is its objective or purpose, WHY should the article be read, HOW will the reader benefit, and so on. What sets YOUR article apart from others on the same subject?

    • Mention what IBM products your article references.
      Be sure to mention what IBM products (and versions) apply to your article.

    • Tell us about you.
      Provide a short biography of yourself. Who do you work for and what do you do? Have you published before? Give us a brief idea of your experience with the topic. What are your other areas of expertise?

  • In your article

    • Make it interesting and understandable.
      Your article must be logical, organized, and plainly written. Have a beginning, middle, and an end. Don’t just state facts or list steps: tell a story, solve a problem. Always know what point you are trying to make throughout the article.

    • Explain as you go.
      Don’t just put your knowledge on paper, use it to educate. Readers want to learn from you, so be sure to teach: when describing how to do something, also explain why, when, and with what, define terms and acronyms, and so on.

    • Acknowledge the reader.
      Address the reader directly throughout the article, but also acknowledge any difficulties and challenges that the reader might be experiencing with this topic. Explain how the article can help.

    • State assumptions and prerequisites.
      If you’re writing at a lower level for a very technical audience, make sure you state knowledge prerequisites. If specific products and versions are required, list them.


What authors want to know

Here are some questions we are asked on a regular basis:

  • How do I submit my article to be published?
    Use the online submission tool to submit your abstract, article draft, or sample materials to developerWorks for evaluation. Be sure to indicate the primary IBM brand or technology area most applicable to your article so that your proposal is directed to the appropriate area.

  • Do I get paid for my article?
    Currently, do not offer monetary compensation for items published on developerWorks WebSphere.

  • I submitted my article proposal last week. Why haven't I heard anything yet?
    We probably just haven't gotten to it. The same staff members who read, edit, produce, solicit, and publish developerWorks articles -- and maintain the Web pages that are updated every week -- are the same staff members who read, research, and evaluate all the article proposals we receive. Due to our continuous publication schedule, please allow up to 6 weeks to receive a response.

  • Why did you reject my proposal?
    If we do not accept your article, we will usually offer a brief indication of the reason. But don't be discouraged. We receive more proposals than we can publish, so if we say no to yours, please try again -- but with a different proposal. Use the tips in this article to set your proposal apart.

  • Can I submit my article to other publications while developerWorks decides whether or not to accept it?
    Unfortunately, we do not accept simultaneous submissions. If your article gets published elsewhere, send us the URL and we might link to it. Otherwise, if we are unable to accept your proposal, you are free to pursue other avenues for publication.

  • How long after I submit my final draft will my article be published?
    This will depend on your editor, but usually within 8 weeks.

  • I'm not sure if I should write an article, a tutorial, or a series of articles.
    If you're not sure which format is best for your article, then don't worry about it and just write it. Your editor will be able to decide the best presentation for your article. (Remember that if you propose a series of articles, you commit to completing the entire series. In most cases, you will not be paid for any articles until the final installment has been published.)

  • Can you review what I have written so far before I continue working on my article?
    We are generally unable to review interem drafts of your article. We begin our editorial process with your final draft; this is not the version that is published, but the version that we edit, so there will be opportunities for changes and reviews before our edited version is published.

  • My article was published somewhere else. Will you republish it?
    No, but we might link to it. Send us the URL.

  • Can my article include screen captures, diagrams, and other images?
    Absolutely. Visual elements enhance the readability and value of an article. Be sure to label each graphic image with a number and caption in your article (for example, Figure 1. Sample configuration) and include a separate .jpg or .gif file for each image. All graphics are resized, recreated, or otherwise optimized by our graphics team to ensure conformity to developerWorks standards.

  • Can I include files with my article for the reader to downbload and use?
    Yes, you can include sample code that you created for use as an example only. You may not include any IBM product code, code from any vendor product, or any open source code. In these cases, you can include links to Web sites where the reader can download these items. You may not include any executable code other than for demonstration purposes.

  • Can you guarantee that you will publish my article exactly as I submit it?
    Unfortunately, no. In fact, we guarantee the opposite. We commonly alter wording to enhance the flow and readability of every article, or to conform to developerWorks standards for language, format, and nomenclature. We also have standards that could require alterations to code formatting, tables, and images. However, in all cases we make these changes with great care so that your original technical meaning is not affected. You will have the opportunity to review our edited version prior to publication and make comments or corrections, but the feedback we receive from nearly all our authors maintains that our edits improve the quality and value of the article.


What authors need to know

Here are some questions that we are not asked often enough:

  • What kinds of topics should I avoid?

    • Anything routinely covered in product documentation, like product installation and configuration.
    • Very specialized topics that have limited appeal.
    • Topics involving older products that are no longer supported by IBM. Unless unusual circumstances compel your article to be published, we generally seek articles that support the newest available versions of IBM software.
  • Are there any topics that are particularly desirable?
    Topics that are valuable to you as a practitioner are the topics we want you to propose. Additionally, articles on new IBM products (or new releases of existing products), or how hot new technologies can be used with IBM products are also good subjects to propose, since reference material in these areas is usually very limited. Topics that demonstrate interesting ways WebSphere software can be used with other IBM or vendor software are also great.

  • Does anyone review my article after I've written it?
    We will have one or more IBM subject matter expert review your final draft for technical accuracy. If a reviewer has questions, comments, or corrections, you will need to resolve them and create a new final draft before we begin our editorial process. If you are an IBM employee, you must enlist your own subject matter experts and incorporate their review comments before submitting your final draft to your editor. You must also supply the reviewers’ names and their comments for our records.

  • Can I quote other sources in my article?
    Yes, as long as you attribute the quote to the source immediately following the quote and include a link to the original source in the Resources section. However, you should avoid lengthy quotes, since they often require permission from the original publisher. Otherwise, you must never include material extracted from other sources in your original work. Plagiarism is not tolerated to any degree under any circumstances.


Conclusion

If you're interested in sharing your experience and knowledge with others by writing technical articles, use the tips presented in this article and the information available in the Resources below to fine tune your ideas, elevate your proposals, and create compelling content for the developerWorks audience. Check back here again as we add more suggestions to enhance your articles and their value to developers everywhere.

Resources

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 WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=279826
ArticleTitle=Tips to help you get published on developerWorks
publish-date=01282009