Thinking about writing a technical article and getting it published in a technology zone on the developerWorks Web site? Find everything you need to get started writing for the developerWorks technology zones (AIX and UNIX, Java technology, Linux, Open source, SOA and Web services, Web development, XML, as well as Industries and Cloud computing) in this best-practices article, compiled by the developerWorks staff. We look forward to working with you to help you bring your content from the idea stage to a published Web page. This article is organized into the following sections:

• The idea stage
• The writing process
• The submission process
• Author recognition

The idea stage

You have great ideas for technical articles, and the editorial staff for the developerWorks Web site will work with you to get your ideas developed into high-quality Web content. You might have a technical topic in mind already, or you might want to check out the wish list of topics that the dW editorial staff maintains.

Overall, your content should:

• Be written for the software developer audience.
• Be your original work. This includes not only your article body, but your title(s), images, and code samples. If any part of your content is borrowed from another source, it is imperative that you obtain permission to use the content from the original owner and provide the proper citations in the content. If you have questions on how to do this, ask your developerWorks editor.
• Contain technical how-to information about one or more technologies. Code snippets illustrating a particular task are very popular with audiences, as are end-to-end applications with downloadable source code. Include tested, original code, if applicable. If you borrow code samples from another source, you must first obtain permission from the owner and you must cite the sample properly.
• Provide significant educational value for current or potential IBM customers.
• Describe and show how to use current technology.
• Fill a customer need, for example, by walking through how to solve a realistic business problem.
• Not duplicate information already available in other articles, IBM Redbooks, whitepapers, other IBM Web space, or outside sources.
• Be clear, organized, unambiguous, and state and meet objectives set out in your value statement (described in the next section).

Communicate with an editor early and often!

Because of the high volume of submissions we receive, we ask that you either contact the editor for the content area you're interested in writing for, or use our content submission form to communicate with our editorial team before starting to write your article or tutorial. If you submit a final draft of content before talking with a developerWorks editor, you run the risk of having your work rejected for many factors: the site might already feature content on your proposed topic, or your content might not fall within our content plans at that time. It's safer to determine the need for your content idea before beginning writing by communicating with an editor.

Back to top

The writing process

So, let's say you have communicated with a developerWorks editor and received the go-ahead to start writing your article or tutorial. Congratulations! The next phase of the process is probably the most challenging because it requires creativity, innovation, testing, and approval.

Writing creatively

The hardest part of getting started on writing an article or tutorial is getting started. A good writer does not attempt to write a complete piece in one session; good writers know that writing top-quality material takes many iterations. Most likely you'll need to write, edit, revise, and rewrite your content several times. Often, "sleeping on it" helps if you find you've run into writer's block.

For many writers, it helps to start with an outline that details your goals for the content. Other writers like to start writing "backwards"; that is, jot down a conclusion, which explains what the reader has just accomplished by using the content, and with a specific goal written down, the writer circles back and captures the steps the reader needs to follow to reach that goal.

Remember that developerWorks content focuses on how-to information targeted at software developers. You'll rarely go wrong if you break down your content into manageable chunks of information that correspond to the steps a developer will need to perform. Put pen to paper or finger to keyboard and just begin articulating your idea, knowing you'll be revising it later. For more author guidelines and links to our editorial policy and templates, see our author guidelines.

Your title and abstract

A compelling title and an abstract that contains a value statement are essential to a strong developerWorks piece. Because research has shown that readers of Web material devote mere seconds to deciding whether or not to read a piece of content, your job is to make your title, subtitle, and abstract immediately engaging to entice the reader to spend some time reading your content. Your value statement should state the objectives of your content and describe what the developer gains by reading it. Dry, uninteresting titles and abstracts compel the busy developer to move on without reading further. Pack your titles and abstract with popular keywords to help search engines find your content.

The article body

As you begin designing your information, keep the following tips in mind:

• 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 and second person ("you") where possible, as though you're speaking directly to the reader.
• Write descriptive headings for sections. Make your headings specific and concrete; empty headings devoid of technical content such as "Going further," "Next steps," "Considerations," and so on.
• List task steps, if any, clearly and in numbered lists, rather than burying them in hard-to-follow paragraphs of text.
• Explicitly identify all IBM products that your article applies to, including full product name, edition, and version. For legal reasons, we cannot refer to IBM products by commonly used acronyms, such as WSAD, WAS, WEMP, 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 any IBM products you mention.
• Define technical terms and avoid jargon.
• Define acronyms and abbreviations on first occurrence if they're likely to be unfamiliar to your intended audience (for example, "message-driven beans (MDBs)").

Originality

We don't consider publishing 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 publishing 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, including code samples. See Plagiarism for more information.

Legal and technical sign-offs

You are responsible for ensuring the technical accuracy and legal conformance of the article content and code samples. For code samples that can be downloaded from your article or tutorial, you must verify the following:

• It is original code written by yourself.
• Your immediate manager has cleared the sample code for public release.
• The IP attorney for your area has cleared the sample code for public release.

Note: If the code is not original, or if the code is governed by any other license, we will not publish the code. If you need to use third-party code to demonstrate a point, you should point to another Web site where the code is hosted; not have developerWorks rehost the code.

Graphics

When writing your content, you may want to include complimentary visual aids, such as:

• Screen captures
• Tables
• Conceptual diagrams
• Flowcharts
• Graphs

Use graphics and screen captures judiciously. For example, it's not necessary to include screen captures for every step in a task, but you should definitely use them where they are useful to show complex steps or screens. We will remove any graphics that we think are extraneous or unnecessary. 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 submit them as GIF, JPG, BMP, Photoshop (PSD), or PZD files. "Illustrating your article or tutorial for developerWorks" gives you all the information you need to get started.

Accessibility

In the United States and many other countries, laws require that we make sure that all Web content is accessible, or readable in some way, by people who have impaired vision or are blind, as well as those who have impaired hearing or are deaf. Regardless of regulations and company policies, it's simply fair to give everyone an equal opportunity to learn. But in addition to the satisfaction of knowing that you did the right thing, you'll benefit in several ways, too:

• You will reach a wider audience, because more people will find it in searches.
• Your article will be easier and faster to read, thus more people will actually read the entire article.
• Your article may be published sooner, because it will take less editing and production time if you follow these instructions.

Remember this: Anything that the reader must know or do needs to be in text, too, not just in images.

1. Include figures, captions, and alt tags for all illustrations. Write captions and alternative text (alt) tags for every screen capture or illustration. Limit the alt tags to 50 characters (we can edit them for length, if necessary).
   • Captions state what the image is or what it means in this context.
   • Alt tags need to describe what the image looks like or reveals for those who can't see the screen capture or illustration.
2. Convey code to all readers. Do not use screen output as an image for any code that readers must do something with or know about. Instead, insert the code as plain text so that everyone can read it.
3. Use text colors and formatting that everyone can read. Do not use red or green text or colored highlighting anywhere, because colorblind people cannot distinguish it from other text or elements.

"Web content accessibility for authors" explains how to write and format your articles, tutorials, and Web pages to ensure that they comply with federal laws and corporate policies and reach more readers.

Your conclusion

Use your conclusion, or summary paragraph, to wrap up or review what you have just explained. Restate your original value statement introduced in your abstract, and describe how the reader has attained it and can apply it.

Author biography

Your brief biography should include:

• Your job title
• Related experience and education. Explain what makes you a expert on this topic.
• Optionally, your hobbies or things you enjoy outside of work.

The Resources section

developerWorks receives frequent feedback on the usefulness of our annotated resources, which we include in all content. The Resources section should provide links to related information, especially articles published on developerWorks, related product or technology documentation, pertinent IBM content, pertinent third-party content from well-known experts in the field, and any other relevant information that you think will be useful for your reader.

To keep readers engaged with your content, and not wandering away mid-article to pursue some other author's content, try to minimize off-site links in the body of your article. Instead, in the body, link to the Resources heading and include related content (articles, tutorials, developerWorks downloads, views, technical briefings, Webcasts, demos, books, Web sites, or offers) and URLs there. Likewise, for code downloads and demos, don't include the URLs in the body; rather, link to the Downloads section and include the URLs there.

On the other hand, link freely to elements within the article, such as headings, figures, code listings, and tables, and to other developerWorks content, especially if the article is part of a series. For serial content, include at least one link to the entire series in the body of the article. (In addition, include a link to the entire series in the abstract and Resources section.)

Testing and approval of your document

You are responsible for obtaining all necessary technical reviews of your material (including a legal review if necessary) and signoffs before submitting the final draft to developerWorks. You are also responsible for testing all code samples you submit to ensure that they are working correctly.

Plagiarism

developerWorks does not accept work that contains any plagiarized material, including material taken from product documentation, IBM Redbooks, other developerWorks articles, or any other IBM or non-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. For more information about what constitutes plagiarism, read "What is plagiarism?" on the Plagiarism.org Web site (see Resources for a link).

Back to top

The submission process

You should submit your articles in our developerWorks template, which you can download from one of the following informative articles:

• "Authoring with the developerWorks XML templates"
• "Authoring with the developerWorks Word or Writer templates"

Do not submit PDF files. Our editors work with all articles in XML and transform them to HTML.

A completed draft of your article is generally due six to eight weeks before the scheduled date of publication. Please submit the following to your editor in a ZIP file via e-mail:

• A suggested title (we reserve the right to change titles to meet our conventions)
• A brief author biography and author headshot photo (optional) for each author
• The draft itself in the XML, Word, or Writer template, already run through a spell-checking program (please name it index.xml)
• All graphics in JPG or GIF format
• 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. As soon as the review is complete, we'll contact you for approval of any major changes we've made. If there are few alterations to your article, we'll prepare it for publication and send you a final review copy for your approval. Even after receiving a completed draft, we must reserve the right to postpone publication or to refuse publication under the following circumstances:

• We discover that the content (or significant portions thereof) has been previously published. It's very important to ensure that you submit original work to us, or properly cite content that has been taken from another source.
• 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. In that case, you have the right to withdraw your submission and to offer the original (unedited and unreviewed) content to another publication.

Back to top

Author recognition

You can receive recognition for your contribution through the IBM developerWorks Author Achievement Recognition Program.

The IBM developerWorks Author Achievement Recognition Program is a merit program that formally acknowledges the publishing achievements of developerWorks contributors. Participants earn points for contributions and work toward the following levels of achievement:

• Contributing author: An IBM developerWorks Contributing Author is a repeat contributor to developerWorks who has independently authored at least one major content item.
• Professional author: An IBM developerWorks Professional Author is a frequent developerWorks contributor who is also an active technical reviewer and a mentor to aspiring developerWorks authors.
• Master author: An IBM developerWorks Master Author is an authoritative technical contributor who has demonstrated the highest level of integrity and commitment to sharing technical knowledge.

If you are a current or recent author, past contributions to developerWorks may be applied to program requirements, if eligible. Read the program details to learn how the program works and how you can take advantage of it.

Back to top

Thank you

We thank you for your interest in developerWorks, and appreciate the excellent content that you submit to us. Without your content, it would be difficult for us to earn all the industry awards that we have been given, not to mention the trust our audiences have in the resources we provide to them.

Resources

Learn

• "Authoring with the developerWorks XML templates": Download the developerWorks XML templates and find all the information you need to use the templates to compose your article.
  
  
• "Authoring with the developerWorks Word or Writer templates": Download the developerWorks Word or Writer templates and find all the information you need to use the templates to compose your article.
  
  
• "Illustrating your article or tutorial for developerWorks": Learn how to create and deliver effective graphics such as screen captures, diagrams, and photographs to enhance and help explain your content.
  
  
• developerWorks author guidelines and editorial policy: Learn more about our editorial policy.
  
  
• Content submission form: Submit an article or tutorial idea to developerWorks, and start talking with a developerWorks editor. Check to see what content is most desired in the editors' content wish list.
  
  
• Plagiarism: Review tips for avoiding it at the Plagiarism.org Web site.
  
  
• "Web content accessibility for authors": Learn how to write and format your content to comply with federal laws and corporate policies that guarantee accessibility for all readers.
  
  

Discuss

• developerWorks editor contact info: If you have questions, contact the editor for the technology or product zone you're interested in.
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• The idea stage
• The writing process
• The submission process
• Author recognition
• Thank you
• Resources
• About the author
• Comments