Writing articles for developerWorks WebSphere

Everything you need to know from submitting an idea to getting it published

This article steps you through the process of submitting an article proposal to the developerWorks WebSphere® team, writing the article, and getting it published on developerWorks WebSphere. You'll learn about the kinds of articles we're looking for, our style and formatting guidelines, and how to submit your article draft. We'll also cover important topics such as plagiarism and copyright information.

developerWorks WebSphere Editorial Team (ramaker@us.ibm.com), Content Editors, IBM

This content is brought to you by the developerWorks WebSphere editorial team: Jim Mann, Jim Ramaker, Chris Rothemich, Scott Shekerow, and Dorothy Wu.



18 May 2011 (First published 25 January 2006)

Step 1: Decide what to write about

Our goal for developerWorks WebSphere is to publish articles and tips that directly meet the needs of our business and technical users. Our content describes concepts or tasks that are not ordinarily described in depth (or at all) in the product documentation. We want to explain how to apply WebSphere technologies to solve real-world problems.

developerWorks WebSphere publishes tips, articles, and tutorials. We're interested in the following types of articles:

We're looking for content that:

  • Contains how-to information about one or more WebSphere products.
  • Provides significant educational value for current or potential IBM customers.
  • Describes and shows how to use current technology.
  • Fills a customer need, for example, walks readers through how to solve a realistic business problem.
  • Does not duplicate information already available in product documentation, other articles, Redbooks or other sources. For example, there is usually plenty of documentation that explains how to install software, so you probably don't need to put this in your article.
  • Is clear, organized, unambiguous, and states and meets objectives.

Step 2: Submit your idea

You can submit content ideas and proposals using the developerWorks proposal submission form. Make sure to select WebSphere as the brand. Note: Although many BPM products are no longer branded WebSphere, they are still part of AIM, so select WebSphere for these submissions, as well.

Alternatively, if you know the WebSphere editor responsible for your topic, you can sumbit an email proposal directly to the editor.

Your proposal should include:

  • A brief explanation of what you want to write about. Your proposal should have an appropriate topic and shouldn't duplicate another piece of content already published on developerWorks.
  • The reasons why you think readers will benefit from your article or tip and why you're the right person to write it (explain your expertise).
  • An outline listing each topic you'll cover. This helps you develop your thinking and lets us know exactly what you plan to cover.
  • Your contact information (including email address), so that we can contact you.
  • Optionally, any sample code that may accompany the content. Note that IBM employees are responsible for obtaining all required management and, if necessary, IP law approvals for external publishing prior to submitting your final draft to developerWorks. An authorization note from your manager is our confirmation that these approvals have been obtained.
  • You may include a draft of your article if you have one completed. However, as a general rule, we don't recommend writing drafts before your proposal has been accepted.

Because of the volume of submissions we receive and the time required to evaluate each one, we may take 4-6 weeks to respond to a proposal. If we're interested in your proposal, we'll contact you by email. We may ask to review a partial or complete draft of your work before accepting it. All work is done on speculation, meaning that we reserve the right to refuse the draft if we determine that it either doesn't suit our content needs or isn't of publishable quality. Acceptance of a proposal does not guarantee acceptance of the final article.

If we accept the draft, we'll work with you to edit the content, ensure that it's technically reviewed by appropriate subject matter experts, schedule the article for publication, and assign a deadline for your final draft.

For more information on what kind of content we're looking for and how to improve the chances of getting your proposal accepted, see Tips to help you get published on developerWorks.

Step 3: Write your article

Once you've submitted your proposal and we've accepted it for potential publication, you're ready to begin writing the article. Following are some guidelines that will help you in developing your article:

  • Verify that all products and product functions that you reference in your article are generally available.
  • Cover your topic thoroughly and in a logical sequence. Include only relevant information and exclude extraneous details.
  • Write in a professional and positive tone, and in a style appropriate for your audience. A casual and conversational tone is acceptable and appropriate, but overly informal language and disparaging or heavily opinionated comments are unacceptable.
  • Use active voice.
  • Write descriptive, task-oriented headings for sections. Aside from "Introduction" and "Conclusion", make your headings specific and concrete, such as "Create the monitor model" rather than "Monitor model." Avoid headings devoid of content such as "Getting started," "Next steps," "Considerations," and so on.
  • List all task steps, if any, clearly and in numbered lists, rather than burying them in paragraphs of text. This is a common problem.
  • Explicitly identify all IBM products that your article applies to, including full product name, edition, and version, such as WebSphere Application Server Version 7. For legal reasons, do not refer to IBM products by commonly used acronyms, such as WSSR, WAS, WBE, WPS, or RAD. Some product names have approved short names, which can be used after the first occurrence, such as "WebSphere Studio Application Developer (hereafter called Application Developer)." Your content editor, brand manager, or IPL attorney will help you determine whether an approved short name exists for your product.
  • Define all technical terms you use and avoid jargon.
  • Define acronyms on first occurrence if they're likely to be unfamiliar to your intended audience (for example, "message-driven beans (MDBs)").
  • Use italics only for book titles and new words defined in the text.
  • Use bold for all selectable or clickable user interface elements, such as "Click New."
  • Use monospace font for examples, code snippets, text or commands the user enters, and all method and class names.
  • Use plain text for window or dialog names, view names, and file names.

Be original

We do not publish content that has already been published elsewhere, including other areas of developerWorks, third-party publications (print or web), and personal web sites. We will consider simultaneous submissions, but require that you notify us if you have submitted an idea to more than one publication at a time for consideration. All work must be original and unique.

We will not accept work that contains any plagiarized material, including material taken from product documentation, IBM Redbooks, other developerWorks articles, or any other IBM sources, even if we have accepted your content idea. If you must borrow ideas or content from another source, you must credit the source properly. To present someone else's work as your own is plagiarism and is in violation of U.S. copyright law.

Upon the first occasion, we'll immediately send the article back to you for revision with the expectation that you will remove or properly accredit all plagiarized sections. If plagiarism occurs again, we'll refuse the draft that you send and will no longer accept any work from you.

For more information about what constitutes plagiarism, see "What is plagiarism?" on the Plagiarism.org Web site.

Illustrate your article

When writing your content, you may want to include:

  • Screen shots
  • Tables
  • Conceptual diagrams
  • Flowcharts
  • Graphs

Use graphics and screen shots judiciously. For example, it's not necessary to include screen shots for every step in a task, but you should use them where they are useful to show complex steps or screens. We will remove any graphics that we think are extraneous or unnecessary.

Don't use screen shots to present sample code. Screen shots may be difficult to read, are not accessible to screen readers (and therefore, to those who are visually impaired), and are not visible to users who view the content with graphics turned off in their browser. Instead, include the code inline or in code sections in the body of the article.

Article graphics can be no more than no more than 580 pixels wide. We will resize or crop any graphics wider than this and format images when necessary, if you don't have the tools to do so.

Submit all graphics with the final draft of your content. You can send them as GIF, JPG, or BMP files.

For more information, refer to Illustrating your article or tutorial for developerWorks.

Provide contact information

Unless requested not to, we will publish author e-mail addresses in your article. If you do not want your e-mail address published, you must specifically request that when you submit your article to us.

Provide downloads

It's a good idea to provide code samples for download with your article, if applicable. If you have code samples or other downloadable information you want to include, combine them in one or more ZIP files and submit them with your final draft. Note that IBM employees are responsible for obtaining all required management and IP law approvals for external publishing prior to submitting your final draft to developerWorks. An authorization note from your manager is our confirmation that these approvals have been obtained.

Organize your article

The body of your article should typically include the following sections:

  1. An overview section that introduces the article, including:
    • A compelling lead paragraph that grabs the readers interest
    • A brief description of the feature or task that will be covered in the article
    • A brief synopsis of what the article will cover
    • Guidelines or prerequisites for the article and the assumed technical experience of the reader
  2. A section that lists all system prerequisites and configuration information.
  3. An in-depth section that fully describes the subject, such as:
    • A detailed feature description
    • Benefits of this feature and how it is used
    • How the feature was designed or developed (what the challenges were; how these challenges were met)
    • Associated graphics, diagrams, charts, tables, or code samples
  4. For tasks, one or more sections that include:
    • Specific steps for completing the task. Make sure you explain the reasons for each step.
    • Appropriate screen shots, where necessary. See Graphics for guidelines on appropriate use of screen shots.
  5. A customizing section (optional), which may include:
    • A description of how or why users might customize the technique to suit their needs.
    • Any necessary troubleshooting information for the feature or task.
  6. A summary that wraps up or reviews what you have just explained and describes what the reader has learned and how they can apply it.
  7. A brief biography for each author, which should include:
    • Job title, including level (such as Senior IT Specialist).
    • Your related experience and education. Explain what makes you a expert on this topic.
    • Optionally, your hobbies or things you enjoy outside of work.
  8. Links to related information, especially articles published on developerWorks, related product documentation, pertinent IBM Redbooks, and any related IBM product or marketing information.

Step 4: Format your content for developerWorks

You can develop your articles using Microsoft® Word or OpenOffice.org Writer, or in the developerWorks XML template. Do not submit PDF files. Our editors convert all articles to XML and transform them to HTML. When your proposal is accepted, your editor will work with you to determine the format in which they would like to receive your article draft.

You'll find the developerWorks templates and detailed instructions on how to use them here:

Step 5: Submit your content

A completed draft of your article is generally due four to six weeks before the scheduled date of publication. When you submit your completed draft, make sure to include the following:

  • A suggested title (we reserve the right to change titles to meet our conventions.
  • A brief author biography.
  • The names of at least two subject matter experts who have reviewed the draft for technical accuracy.
  • For IBM employees, a note from your manager indicating approval to publish the article on developerWorks. Note that IBM employees are responsible for obtaining all required management and IP law approvals for external publishing prior to submitting your final draft to developerWorks. This authorization note from your manager is our confirmation that these approvals have been obtained.
  • All graphics in JPG or GIF format. (Refer to Illustrating your article or tutorial for developerWorks for more information.)
  • All downloads in ZIP format.

After you submit the completed draft, our editorial staff will carefully review the entire package. At this time, we may rewrite sections of your draft to make it clearer and to adjust the wording of the content to fit our style or format. Or, we may send the draft back to you with recommendations for revision. No article on developerWorks WebSphere is published without thorough editing and technical review.

Once the review is complete, we'll copyedit the content and prepare it for publication.

Even after receiving a completed draft, we reserve the right to postpone publication or to refuse publication under the following circumstances:

  • We are unable to obtain a thorough technical review of the article. This may occur if technical reviewers are unavailable or unwilling to review a draft.
  • The article content cannot be shared publicly until a later date, or we feel that a later publication date is more appropriate due to a product's release date.
  • We discover that the content (or significant portions thereof) has been previously published.
  • The submitted draft is deemed unworkable from an editorial perspective.
  • The author is unresponsive to requests for changes.

As an author, you may not agree with our editorial decisions or with the technical review comments. In that case, you have to right to withdraw your submission and to offer the original (unedited and unreviewed) article or tip to another publication.

Author recognition

The developerWorks Author Achievement Recognition Program formally acknowledges the publishing achievements of developerWorks authors. By participating in the program, you can earn professional designations that represent the level of your published contributions to developerWorks and the extent of your participation in the developerWorks community. Achieving a professional designation from the dW Author Achievement Recognition Program:

  • Earns you a title that identifies your prestigious achievement and supplements your professional accomplishments.
  • Confirms that you have published a body of work that has been recognized for its technical and educational value by industry colleagues.
  • Demonstrates your ability and commitment to knowledge sharing on standards-based or emerging technologies, IBM products, or a combination of these areas.
  • Promotes your technical depth and expertise.
  • May help establish or enhance your authority in your areas of expertise to a worldwide audience.

For more information about the Author Achievement Recognition Program, including how to register, refer to IBM developerWorks Author Achievement Recognition Program.

Payment policy

developerWorks WebSphere encourages you to submit your content ideas, but we do not pay for articles or other content. This payment policy applies to WebSphere submissions only. Other content areas of developerWorks may have different payment policies.

Copyright policy

All content published on developerWorks WebSphere is copyright protected. This means that no part of an article may be reproduced or transmitted in any form or by any means without the prior written permission of the developerWorks WebSphere editorial team. If we publish content that you submit, that content is a "work made for hire," as defined in Section 101 of the Copyright Statute; and IBM owns the submitted content. This prohibits you from publishing the content in any other publication.

If you have a question about our guidelines or if you have a question not answered here, please contact Chris Rothemich.

Resources

Learn

Get products and technologies

Discuss

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=101514
ArticleTitle=Writing articles for developerWorks WebSphere
publish-date=05182011