Authoring with developerWorks

A step-by-step guide for authors to create articles and tutorials for publication


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.

Content is published on developerWorks in HTML format, but is generated from XML (Extensible Markup Language) format. Your developerWorks editor will convert your Microsoft Word and OpenDocument format (ODT) documents to our XML source format. The success of this conversion to XML depends on how closely the Word or ODT 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.

Basic steps

Create content by following these steps:

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

Step 1. Download the author package

Download the Word author-package zip file if you use Word on Windows®, or the OpenDocument author-package zip if you use an OpenDocument editor 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 opendoc-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.

Step 2. Create your content

In this step, you'll set up your own article 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.

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.
If you are new to writing for developerWorks, we recommend you use a sample article. 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 content, open the appropriate file listed in Table 1.

Table 1. Article templates and samples
Template or sampleProgramFile

When you first open a template, you are prompted to fill in the fields shown in Table 2. If you don't have all the information now, feel free to use the provided default values and update them later.

Table 2. Submission fields to be filled in
FieldOptional or requiredContents
Type of SubmissionRequiredArticle
TitleRequiredTitle of your content.
SubtitleOptionalSubtitle for your content. Optional but recommended.
KeywordsOptionalSearch-engine keywords applicable to your content.
PrefixOptionalPrefix to your name. Examples: Dr., Mr., or Ms.
GivenRequiredYour given name. Example: John
MiddleOptionalYour middle name(s) or initial(s). Example: D.
FamilyRequiredYour family name. Example: Doe
SuffixOptionalSuffix to your name. Examples: Jr., or IV
Job TitleRequiredYour job title. Example: Senior programmer
EmailRequiredYour email address.
BioRequiredYour biographical information. Include the experience and credentials that qualify you to write authoritatively on this topic.
CompanyRequiredThe name of your company. Example: IBM
Photo filenameOptionalThe name of a file containing a head-and-shoulders photo of you suitable for displaying with your biographical information.
AbstractRequiredYour content abstract. Put the main points and key phrases at the start of the abstract, because it will be truncated in search results. Aim for three to five sentences that express why the reader would care about the content (motive) and what he or she can gain from reading the content (benefits).

Save your new document using a name of your choice. If you started from a template, be sure to save as a regular document (.doc for Word or .odt for OpenDocument) rather than a template.

Step 3. Edit your content

Edit your content following the guidelines in our sample article 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 content. Extensive comments in the samples guide you through every aspect of coding your content. 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 content. 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 105 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, .gif, or .png files, and be sure they do not exceed 850 pixels in width. Send the artwork files to your editor. See "Illustrating your content 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 content.

Table 3. Recommended highlighting
Highlighted elementRecommended highlighting
"Article titles"Quotes
Book titlesItalics
C/C++ codeCourier or Courier New font
ClassesCourier or Courier New font
Code samples HTML Preformatted style (Courier or Courier New font at 8pt)
Code snippets (less than one line) referenced in textCourier or Courier New font
Column or series namesItalics
Command namesCourier or Courier New font
Directory namesNo highlighting
EmphasisItalics. For example: "Use that to introduce a restrictive clause. Do not type over..."
Exception namesCourier or Courier New font
File namesNo highlighting
Function callsCourier or Courier New font
GUI controlsBold. For example: "On the Installation menu, click Install a new feature > Finish."
Examples of HTML tags or portionsCourier or Courier New font
InterfacesCourier or Courier New font
Keywords (such as static)Courier or Courier New font
Magazine titlesItalics. For example: "See the related article in LinuxToday."
Message text or prompts addressed to the userCourier or Courier New font
MethodsCourier or Courier New font
ObjectsCourier or Courier New font
Path namesNo highlighting
Terms defined in contextItalics
Text entered by usersCourier or Courier New font
Types (such as int or long)Courier or Courier New font
URLsNo highlighting
VariablesItalics. For example: "... where myname represents your user ID..."
XML tags or portionsCourier or Courier New font

Step 4. Send your content to developerWorks

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

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

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

ArticleTitle=Authoring with developerWorks