Authoring with the developerWorks Word and OpenDocument templates

A step-by-step guide for authors to create content for publication on developerWorks

Welcome, authors! This article shows you how to prepare English-language technical content for publication on the worldwide developerWorks site using Open Document Text editors such as IBM Lotus Symphony®, Apache Open Office™, LibreOffice, or another editor that support the OpenDocument format (ODT), or using Microsoft® Word. The steps are simple. You download our template package for either OpenDocument or word, fill in the fields in the template, and then compose your content according to the guidelines in the template. Tips for composing your content and submitting it to the developerWorks staff are also included in this article.

Share:

Ian Shields, Senior Programmer, IBM

Ian ShieldsIan 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.


developerWorks Contributing author
        level

23 August 2013 (First published 12 July 2007)

Also available in Chinese Russian Vietnamese Spanish

Looking for XML templates rather than word processor templates?

If you prefer to compose your content in XML format, we also offer XML templates for your use. See the companion article, "Authoring with the developerWorks XML templates."

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 Downloads below) and unzip the file.
  2. Create your own template in Word or your favorite OpenDocument editor, such as OpenOffice.org 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.


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 OpenDocument 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 content using the 5.12 author package for Word or OpenDocument 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 OpenDocument 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 content, 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>

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.

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. 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
SampleWordsample-article-word-5.12.doc
 OpenDocumentsample-article-opendoc-5.12.odt
TemplateWordarticle-word-5.12.dot
 OpenDocumentarticle-opendoc-5.12.ott

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.


Downloads

DescriptionNameSize
IBM developerWorks author package - ODF, V5.121author-package-opendoc-V5.12_20120830.zip397KB
IBM developerWorks author package - Word, V5.122author-package-word-V5.12_20090320.zip251KB

Notes

  1. Use the ODF (Open document format) version if you are using IBM Lotus Symphony, OpenOffice.org, LibreOffice, or another editor for Open Document Text (.odt or .ott files).
  2. Use the Word version if you are using Microsoft Word (.doc or .dot files)

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


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=XML
ArticleID=240075
ArticleTitle=Authoring with the developerWorks Word and OpenDocument templates
publish-date=08232013