Getting started

The editors at developerWorks look forward to working with you to publish your content. Please be sure you have presented your idea to a developerWorks editor and have obtained his or her approval to proceed with your content before using these instructions. If you haven't already, you can use our content submission form to submit your idea.

Articles and tutorials are published on developerWorks in HTML format, but are generated from XML (Extensible Markup Language) format. Your developerWorks editor will convert your Microsoft Word and OpenOffice.org Writer documents to our XML source format. The success of this conversion to XML depends on how closely the Word or Writer document that you submit follows the guidelines in the templates you'll be using.

If you are familiar with using styles in a word processor, you'll find our templates easy to use. If not, the templates contain detailed instructions on how to apply styles that match the composition tips and highlighting conventions described here.

Back to top

Article template or tutorial template?

If you've browsed the developerWorks site, you know that authors contribute both articles and tutorials to developerWorks. Their format and purpose differ. Your developerWorks editor can help you decide which format better suits your content idea.

Tutorials

• Tutorials have educational objectives; they teach. Rather than simply listing steps, tutorials explain why the step is done and how it relates to the overall objective. Tutorials spell out their educational objectives and time to completion (usually around two hours). After completing a tutorial, the reader should be able to repeat the learned task independently.
• Tutorials can teach concepts or how to complete tasks. Many tutorials teach both concepts and tasks, and encourage readers to try the tasks while reading. To make it easy to follow along, tutorials often include sample code and advice for setting up the reader's environment. Tutorials also often chunk content into discrete and manageable tasks that make up the whole.
• Tutorials published after March 1, 2009, don't require registration.
• Tutorials average 20 to 30 pages when printed. And because the task may take several hours to complete, many readers print the tutorial PDF for reference during or after the task.
• A tutorial can stand alone or be one part of a multi-part series.

Articles

• Like tutorials, articles often teach, but less overtly than tutorials. Articles don't spell out their educational objectives or time to completion.
• In addition to instructing readers on a particular task, articles can also introduce new concepts, architectures, or product features. These kinds of articles aim to raise readers' awareness and whet their appetite to learn more (perhaps by taking a developerWorks tutorial!). Other kinds of articles take a more persuasive tone, where the author shares his or her unique approach, perspective, or experience. And other kinds of articles delve into a new product or technology by interviewing an expert or reviewing current literature on the topic.
• Articles don't require registration.
• Articles average 10 pages or fewer when printed. Readers generally read article content online.
• Like tutorials, an article can stand alone or be one part of a multi-part series.

Back to top

Basic steps

Create an article or tutorial by following these steps:

1. Download the author package for Word or Writer (see Downloads below) and unzip the file.
2. Create your own article or tutorial template in Word or Writer, from the template file or by copying the sample article or tutorial.
3. Edit your new article or tutorial to add your content, being sure to follow the guidelines in the template or sample.
4. Send your article or tutorial, along with any separate files, such as images or code downloads, to your developerWorks editor.

Back to top

Step 1. Download the author package

Download the Word author-package zip file if you use Word on Windows®, or the Writer author-package zip if you use Writer on Windows or Linux®. Place it in a suitable location (for example, C:\ on Windows or your home directory on Linux) and unzip it.

After you unzip the file, you should see a developerworks directory (or folder) containing either a word-templates or writer-templates subfolder, depending on which package you downloaded.

The files and tools included in the author package are designed for use on Linux or Windows. If you need assistance editing the templates using an operating system other than Windows or Linux, please contact your developerWorks editor.

Back to top

Release notes

Before moving on to Step 2, let's preview what's changed in this release. The version 5.12 author packages for Word and Writer were released to authors on March 23, 2009. The templates in those packages conform to the 5.12 version of the developerWorks XML schema and stylesheets. You should prepare your article or tutorial using the 5.12 author package for Word or Writer as appropriate. If you are using an earlier release, you'll need to download the 5.12 author-package.zip file from the Downloads section below.

The 5.12 release of the Word and Writer author packages includes internal changes for supporting PDF generation and developerWorks micro sites. Both packages are synchronized with the 5.12 version of the developerWorks XML schema and stylesheets. In other words, when your developerWorks editor transforms the XML you submit, the HTML output will be valid and current. The external change of interest to authors, as reflected in the updated templates for articles and tutorials, is:

• In the "Get products and technologies" section of Resources, the IBM product trials bullet includes updated text and coding. If you use the product trials bullet, please make sure you pick up the new XML templates or change that bullet to:

  <resource resource-category="Get products and technologies">Download <a href="http://www.ibm.com/developerworks/downloads/" onmouseover="linkQueryAppend(this)">IBM product evaluation versions</a> or <a href="http://www.ibm.com/developerworks/downloads/soasandbox/" onmouseover="linkQueryAppend(this)">explore the online trials in the IBM SOA Sandbox</a> and get your hands on application development tools and middleware products from DB2<reg/>, Lotus<reg/>, Rational<reg/>, Tivoli<reg/>, and WebSphere<reg/>.</resource>

  
  

Back to top

Step 2. Create an article or tutorial

In this step, you'll set up your own article or tutorial starting from a template or a sample. Templates and samples each contain examples of most things you can use on developerWorks, including instructions to achieve acceptable formatting and the proper styles to apply.

Template

If you are experienced with writing for developerWorks, you may prefer to start from our templates. When you start from a template, you will be prompted to fill in several fields with required developerWorks information (see Table 2 below), before the instructional material is displayed.

Sample

If you are new to writing for developerWorks, we recommend you use a sample article or tutorial. With a sample, you can get started on your content right away. The required developerWorks information is filled with default values, so you will need to update the fields before sending your content to your editor.

To create your own article or tutorial, open the appropriate file listed in Table 1.

Back to top

Step 3. Edit your article or tutorial

Edit your article or tutorial following the guidelines in our sample article and tutorial files. These show you what style to apply to achieve formatting that will result in a successful transformation to developerWorks XML. It is extremely important that you format your content according to these guidelines. If you have any questions, please contact your developerWorks editor, to ensure that your content is not compromised.

Composition tips

The sample files (see Table 1) are your best source for comprehensive tips on developing your article or tutorial. Extensive comments in the samples guide you through every aspect of coding your article or tutorial. Here are some other tips you might find helpful:

• You can cut and paste from other documents that you may already have. However, you will need to compare the styles that you import with the pasted text to be sure they match our examples.
  
  
• The samples include examples of the constructs most commonly used in developerWorks articles and tutorials. If your content doesn't need something, say a list or a figure, then don't put one in just because the sample has one.
• When including listings of sample code:
  
  
• Confine code line lengths to 90 characters, INCLUDING blank spaces.
• Confine code listing lengths to 100 lines, INCLUDING blank lines.
• Avoid hard-coding blank spaces or tabs at the end of a line of sample code.
• Avoid using tabs at the beginning of a line of sample code. If you must indent, use blank spaces.
• Do not use color. If you want to highlight a portion of your sample code, use bold instead.
  
  
• When providing downloadable sample code, zip the code up and send the zip file to your editor separately.
  
  
• Create all artwork files, including screen captures, as .jpg or .gif files, and be sure they do not exceed 572 pixels in width (for articles) or 500 pixels in width (for tutorials). Send the artwork files to your editor. See "Illustrating your article or tutorial for developerWorks" to learn more about how to create and deliver effective graphics.
  
  

Highlighting conventions

Do you use italics or quotes for a book title? When should you use bold—or no highlighting at all? Table 2 shows the highlighting conventions recommended for developerWorks articles and tutorials.

Back to top

Step 4. Send your article or tutorial to developerWorks

Once you've completed your content, you're ready to send it to your developerWorks editor. E-mail the Word or Writer file for your article or tutorial (along with any associated graphics or sample code) to your editor. For detailed guidelines and tips on creating and submitting graphics for your article, see "Illustrating your article or tutorial for developerWorks."

If you have any questions or problems, please contact your editor for additional help.

Back to top

Downloads

Information about download methods

Resources

Learn

• "Authoring with the developerWorks XML templates" (developerWorks, March 2009): If, instead of using Word or Writer, you prefer to write your content using our XML templates, find complete instructions and templates in this downloadable package for authors.
  
  
• "Illustrating your article or tutorial for developerWorks: How to create effective graphics " (developerWorks, July 2008): Get detailed guidelines and tips on creating and submitting graphics for your article or tutorial.
  
  
• developerWorks author guidelines and editorial policy: Learn more about our editorial policy and peek at each developerWorks editor's content wish list.
  
  

Get products and technologies

• IBM trial products for download: Build your next development project with IBM trial software, available for download directly from developerWorks.
  
  

Discuss

• 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 content wish list.
  
  
• developerWorks editor contact info: If you have questions, contact the editor for the technology or product zone your content relates to.
  
  

About the author

Ian Shields works on a multitude of Linux projects for the developerWorks Linux zone. He is a Senior Programmer at IBM at the Research Triangle Park, NC. He joined IBM in Canberra, Australia, as a Systems Engineer in 1973, and has since worked on communications systems and pervasive computing in Montreal, Canada, and RTP, NC. He has several patents and has published several papers. His undergraduate degree is in pure mathematics and philosophy from the Australian National University. He has an M.S. and Ph.D. in computer science from North Carolina State University. You can contact Ian at ishields@us.ibm.com.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Getting started
• Article template or tutorial template?
• Basic steps
• Step 1. Download the author package
• Release notes
• Step 2. Create an article or tutorial
• Step 3. Edit your article or tutorial
• Step 4. Send your article or tutorial to developerWorks
• Downloads
• Resources
• About the author
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into XML on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers