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 an editor and have obtained his or her approval to proceed with your content before using these instructions. If you haven't already, fill in the Submit content form to propose your idea.

Articles, tutorials, and knowledge paths are published on developerWorks in HTML format, but are written using XML (Extensible Markup Language) format. Prior to publication, the XML source of the content is validated for acceptable markup as defined in the developerWorks schema and then transformed into the HTML for publication using an XSLT (Extensible Stylesheet Language for Transformations) stylesheet. This separation of article content from presentation details helps us use automated processes to manage our large site.

The authoring approaches we offer do not require specialized skills. If you are familiar with XML or HTML already, you'll find our templates easy to use. If not, you can get acquainted with XML by reading the composition tips later in these instructions, and by browsing the New to XML page on the developerWorks XML zone.

While you prepare your content for publication, think about making it accessible to readers who are vision challenged. In other words, supply text alternatives to non-text content like images. Later in this article, you'll see some examples of accessibility requirements for Web content. To learn more about Web content accessibility, skim the Web Content Accessibility Guidelines 2.0 for tips and techniques.

Back to top

Which template?

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

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 average 10 pages or fewer when printed. Readers generally read article content online.
• An article can stand alone or be one part of a multi-part series.

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

Knowledge paths

• Knowledge paths are a new type of content on developerWorks, introduced in the spring of 2011 in beta format, and offered with full function in the fall of 2011.
• Knowledge paths are focused learning guides for IT professionals. They help readers quickly and easily gain the skills that are essential to using IBM products, technologies, and solutions.
• Each knowledge path is a carefully prescribed sequence of diverse resources, including how-to articles, trial downloads, discussion forums, educational videos, hands-on exercises, and much more. Specifically chosen by subject matter experts like you, the resources guide readers from conceptual awareness to task mastery.
• Knowledge paths lead the reader to "next steps" in the learning process.
• A knowledge path can stand alone or be one part of a multi-part series.

Back to top

Basic steps

Create your content by following these steps:

1. Download the author package and unzip the file.
2. Create a folder and XML template for your article, tutorial, or knowledge path using a script from the package.
3. Edit the XML template to add your content, then validate that XML against the schema and correct any errors.
4. Preview your content in a browser to get an idea of how it will appear on developerWorks.

Back to top

Step 1. Download the author package

Download the author-package zip file and place it in a suitable location (for example, C:\ on Windows or your home directory on Linux). Unzip the file.

The developerworks directory does not have to be located in the root directory or even on the Windows C:\ drive. However, the tools assume the location of files within the developerworks directory and its subdirectories, so please keep the developerworks directory structure and file names as is.

If you're using Linux, you should also download an IBM Developer Kit for Java (see Resources for a link), and install it, preferably in /opt/ibm, although you can download a tarball version and install in your home space if you do not have root authority. The validation tools (described in "Using the developerWorks XML validation tools" work only with Java versions that include Xalan (Java version 5.0 includes Xalan 2.7). See that article for more details.

After you unzip the file, you should see a developerworks directory (or folder) containing the following subdirectories:

• readme—contains a readme.html file. This readme file links to this article you're now reading.
• schema—contains the schema files. The main schema file is named dw-document-6.0.xsd. (6.0 is the level of the developerWorks schema at the time of this writing.)
• tools—contains three templates (template-dw-article-6.0.xml, template-dw-knowledge-path-6.0.xml,and template-dw-tutorial-6.0.xml) as well as some simple tools to help you set up and validate a new article. The java subdirectory contains the source of the Java™ programs, which are used with the Linux validation and transformation tool, in case you want to modify or rebuild them.
• web—contains images and JavaScript needed to preview your content.
• xsl—contains the stylesheet files used for preview. The primary stylesheet for each developerWorks site is in a subfolder appropriate to that site, for example: 6.0/en_US/dw-document-html-worldwide-6.0.xsl for worldwide (English) or 6.0/ja_JP/dw-document-html-japan-6.0.xsl for Japan.

The files and tools included in the author package are designed for use on 32-bit or 64-bit versions of Linux or Windows (including Windows 7). If you need help with 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 recent releases.

On May 22, 2012, we made internal updates that do not affect authors. This release does however correct an error in the knowledge path template that was inadvertently introduced in the previous release.

On March 9, 2012, we added support for the new Agile transformation, Business process management, and Mobile development zones.

On November 16 and 28, 2011, we made internal updates that do not affect authors. (The updates improve our handling of rich media and PDFs, and include a new template for landing pages.)

On October 6, 2011, we updated the templates for articles, tutorials, and knowledge paths to include the new rich-media-source element. We also updated some of the comments and samples in the knowledge path template.

On September 1, 2011, we replaced the beta-level support for knowledge paths with full support for authors to create knowledge paths.

On May 27, 2011, we added beta-level support for authors who are creating a new content type, knowledge paths. We also updated internal files for improved maintenance and accessibility across multiple content types; these changes do not affect authors.

On April 21, 2011, we fixed script errors that occur when authors create a new template or transform a template on Windows. This release also includes internal maintenance fixes to the schema, stylesheets, and template that do not affect authors.

On April 18, 2011, we added support for the new IBM i zone.

On January 10, 2011, we added date support for the new calendar year and beyond.

The author-package zip file and this article conform to the 6.0 release. You should prepare your content using the 6.0 schema and stylesheets. If you have used an earlier release of the developerWorks schema and stylesheets, you'll need to download the 6.0 author-package.zip file from the Download section below.

Articles, knowledge paths, and tutorials use the same primary schema (xsd file), but the primary stylesheet varies:

• Primary schema: dw-document-6.0.xsd
• Articles, knowledge paths, and tutorials use a stylesheet appropriate to the local site for which the article is being written. For example, 6.0/en_US/dw-document-html-worldwide-6.0.xsl is used for English-language articles for the developerWorks worldwide site, while 6.0/ja_JP/dw-document-html-japan-6.0.xsl is used for the Japanese local site.

Back to top

Step 2. Create a new template

In this step, you'll set up your own copy of the article, knowledge path, or tutorial template using a tool from the author package. This will create a new file, called index.xml, in a separate directory. It will set up the proper paths and also adjust the template so it works properly in the different operating system environments.

Using Microsoft Windows

In the developerworks directory, double-click new-article.vbs to create an article, new-knowledge-path.vbs to create a knowledge path, or new-tutorial.vbs to create a tutorial. You may choose any valid name as your folder name; the defaults are my-article, my-knowledge-path, and my-tutorial.

After you click OK, you should see a new folder in the developerworks folder. You may need to refresh your view (View > Refresh) to see it. This new folder contains your template (index.xml) and a validation and transformation script (dw-transform.vbs).

Using Linux

Use the new-article.sh, new-knowledge-path.sh, or new-tutorial.sh shell script in the developerworks directory. (If you're running the KDE or GNOME desktops, you can run this from a graphical manager, such as Nautilus or Konqueror; otherwise, run the script in a terminal window.) You'll see a dialog box where you can enter your new project's name.You can choose any valid name; the defaults are my-article, my-knowledge-path, and my-tutorial.

After you select OK (or press Enter), you should see a new folder within the developerworks folder. This new folder contains your template (index.xml) and a validation and transformation script (dw-transform.sh).

Note: If you are using a graphical environment, you will need the appropriate zenity, gdialog, or kdialog package for your GNOME or KDE desktop. If you are using a non-graphical environment, you will need the dialog package.

Back to top

Step 3. Edit and validate your XML

You can choose either of two basic methods for editing and validating your XML source.

Using a validating XML editor

Using a validating XML editor to edit and validate your XML helps you identify any errors as you go. Many commercial XML editors are on the market today for both Windows and Linux. Three examples are Rational® Web Developer for WebSphere® Software, <oXygen/>, and Altova XMLSpy (see Resources for links to downloads and documentation). All three provide free downloadable trial versions, and we recommend that you read the instructions that come with these products to learn how to use them. All the required and supporting files you'll need to use these products, or other commercial XML editors, to develop your article or tutorial are in the developerWorks author-package.zip file.

Some free XML editors are also available. Besides the commercial version of XMLSpy mentioned above, Altova has introduced a free Home Edition of XMLSpy. XML Copy Editor is a free editor released under the GNU General Public License. In addition, plug-ins are available for the Eclipse platform that you can use for preparing XML documents. See Resources for links.

When using a validating XML editor or workbench, keep in mind:

• In the templates that you created with the scripts above, the references to the schema and stylesheet files are relative to your content directory. You may need to change these references to absolute references. For example you may need to change ..\schema\6.0\dw-document-6.0.xsd to something like C:\developerworks\schema\6.0\dw-document-6.0.xsd. You may need to make a corresponding change for the stylesheet, and you will need to change the stylesheet name and location if you want to prepare and article for a local site, such as Japan. In some editors, you may have to specify the location of these files through other configuration means.
• If you transform your content in an XML editor, and none of your images display, it is likely that the editor has created the HTML file in a directory used for temporary storage. If so, you will need to save the generated HTML file in your article directory (my-article, in our example), and open it either in the XML editor GUI or with a browser.

Using a text editor and validation tools

If you can't find a validating XML editor you like, or prefer not to take the time now to learn how to use one, you can use your preferred text editor to edit the XML template and then use the tools supplied in the author package (dw-transform.vbs for Windows or dw-transform.sh for Linux) to validate your XML and transform it to HTML. You can then preview your HTML in a browser. See the companion article "Using the developerWorks XML validation tools" for details on using these simple tools.

Back to top

Step 4. Preview your content

You can preview your article, knowledge path, or tutorial to get a general idea of what the final output will look like. However, there will be some differences between the previewed version and the final version. When you preview your tutorial or article, focus on the content and don't worry about the presentation or style issues. We will make necessary modifications when we do the final edit.

If you are using a validating XML editor, check the documentation for instructions on how to transform the XML into an HTML file and then view that file with a browser. Some editors have a browser preview option to simplify this step.

If you are using a text editor and the developerWorks scripts, your output HTML will be created in your article or tutorial folder. Open index.html with a browser. More detailed instructions on using these scripts are in "Using the developerWorks XML validation tools".

Back to top

Composition tips

The XML files that you generate in Step 2 are your best source for comprehensive tips on developing your article, knowledge path, or tutorial. Extensive comments in the templates guide you through every aspect of coding your content. Here are some other tips you might find helpful:

• Composing in Microsoft Word or OpenDocument formats?

  You can use the Word or OpenDocument templates instead of the XML template; find complete details in "Authoring with the developerWorks Word and OpenDocument templates."

  Alternatively, you can cut and paste from other file formats into the XML template.

  • If you cut and paste from a file with embedded formatting, such as a Word or OpenDocument file, use your editor's capabilities to paste (or paste special) as text, or save the file as a TXT file before you cut and paste from it. Do not cut and paste directly from a formatted file.
  • If your Word or OpenDocument document has embedded images, don't worry about extracting them; simply forward the Word or OpenDocument document to your developerWorks editor, and our team of visual designers will extract and refine the images.
  • If your Word or OpenDocument document has "Track Changes" turned on, be sure to turn it off before you cut and paste into the XML template; otherwise, all your deleted material will reappear intermingled among your text!
• Closing tags. Remember to use closing tags. For example, every paragraph tag (<p>) needs its closing tag (</p>). Also, empty elements like the break tag (<br />) and the image tag (<img />) need a closing slash (/).
  
  
• Tags to avoid. Do not use span tags, code font tags, font classes, or CDATA tags.
  
  
• Code listings. When including listings of sample code inline in your article or tutorial:
  
  
• The maximum code line length is 90 characters, INCLUDING blank spaces. The template has a sample with a ruler line to help you.
  
  
• The maximum code listing length is 100 lines, INCLUDING blank lines.

  If your code listing is longer than 100 lines, segment it into individual listings or excerpt the most important lines, and consider offering the entire code listing as downloadable sample code in the "Download" section of your article or tutorial.

  
  
• Avoid hardcoding blank spaces or tabs at the end of a line of sample code as these are included in the 90 characters per line.
  
  
• Avoid using tabs at the beginning of a line of sample code. If you must indent, use blank spaces.
  
  
• Do not use CDATA tags. If you need to display XML tags, such as angle brackets, in your sample code, use < and > (see the other special characters in Table 1).
  
  
• Do not use color. If you want to highlight a portion of your sample code, use strong emphasis (<strong> and </strong>) instead.
  
  
• Downloadable sample code. When providing downloadable sample code for the "Download" section of your article or tutorial, zip the code up and send the ZIP file to your editor separately.
  
  
• Artwork. Create all artwork files, including screen captures, as JPG or GIF files, and be sure they do not exceed 580 pixels in width. Send the artwork files to your editor. See "Illustrating your article or tutorial for developerWorks" to learn how to more about how to create and deliver effective graphics.
  
  
• Comment lines. To better see your own content as you develop it, feel free to remove the comment lines from the article file as you become familiar with the tagging.
  
  
• Accessibility. Consider the vision-challenged readers and ensure that your article or tutorial satisfies Web content accessibility requirements. Specifically, (1) use color sparingly, if at all, and (2) include text alternatives to non-text content. Typically, this second requirement applies to images in your article or tutorial. Add content before or after any images to sufficiently explain the image to someone who cannot see the image. In addition, provide a short description of the image in the "alt" attribute of the <img> tag. Also, do not create images from tables or rely too heavily on text contained in an image. Examples of these accessibility requirements are covered in greater detail in "Illustrating your article or tutorial for developerWorks."
  
  
• Special characters. Code special characters as shown in Table 1:

For example, to include angle brackets in a code section:

<TABLE border="0" width="100%">

You would code the following in the XML template:

<TABLE border="0" width="100%">

Back to top

Highlighting conventions

Not sure how to highlight code strings? Do you emphasize an article or book title? When should you use no highlighting at all? Table 2 shows the highlighting conventions recommended for developerWorks articles and tutorials.

Back to top

Submitting your article, knowledge path, or tutorial to developerWorks

Once you've finished your masterpiece, you're ready to send it to your developerWorks editor. Email the XML file for your article, knowledge path, 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: How to create effective graphics."

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

Back to top

Download

Information about download methods

Resources

Learn

• "Using the developerWorks XML validation tools" (developerWorks, December 2010): If you prefer to use a text editor to edit the XML template, you can use the tools supplied with the author package to validate your XML and preview your content.
  
  
• "Authoring with the developerWorks Word and OpenDocument templates" (developerWorks, April 2010): If, instead of using the XML templates, you prefer to compose your content in Microsoft Word, OpenOffice.org Writer, IBM Lotus Symphony, or another OpenDocument editor, we also offer Word and OpenDocument templates for your use.
  
  
• "Illustrating your article or tutorial for developerWorks: How to create effective graphics" (developerWorks, April 2010): 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.
  
  
• developerWorks technical events and webcasts: Stay current on IBM products and IT topics.
  
  
• Free developerWorks Live! briefings: Get up-to-speed quickly on IBM products and tools as well as IT industry trends.
  
  
• developerWorks on-demand demos: Watch demos ranging from product installation and setup demos for beginners, to advanced functionality for experienced developers.
  
  
• developerWorks on Twitter: Follow us.
  
  

Get products and technologies

• Microsoft's XML Parser (MSXML) Version 4 or Version 6: To use the dw-transform.vbs script to transform your article or tutorial, you need either version 4 or version 6 of the MSXML parser. The file you need is msxml.msi (version 4) or msxml6.msi (version 6).
  
  
• IBM Developer Kit for Java: To use the dw-transform.sh script on Linux to transform your article or tutorial, you need the IBM Developer Kit for Java, Version 5.0 or later.
  
  
• Rational® Application Developer for WebSphere® Software V7.5: Download a no-charge trial version directly from developerWorks.
  
  
• IBM trial products for download: Build your next development project with IBM trial software, available for download directly from developerWorks.
  
  
• <oXygen/> XML Editor & XSLT Debugger (for multiple platforms) and Altova XMLSpy (for Windows): Learn about or download trial versions of these commercial XML editors.
  
  
• XML Copy Editor: Learn about this fast, free, validating XML editor that can validate and transform your XML files.
  
  
• "XML development with Eclipse" (developerWorks, April 2003): Create XML documents using the Eclipse platform with plug-ins such as Bocaloco Software's XMLBuddy.
  
  
• Evaluate IBM products: Download a product trial, try a product online, use a product in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement Service Oriented Architecture efficiently.
  
  

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 you're interested in.
  
  
• developerWorks community: Connect with other developerWorks users while exploring the developer-driven blogs, forums, groups, and wikis.
  
  

About the authors

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

John Holtman works on the developerWorks Content and Community team. He leads a group that provides level-one support for community-based applications and maintains the site's authoring and editing tools. Since joining IBM in 1983, he has held a variety of positions, most of which have centered around development, design, and delivery of technical and marketing information in print, online, and interactive media. He holds a degree in Communication Arts from the University of Dayton in Dayton, Ohio.

As a developerWorks Web editor, Gretchen Moore has shaped developerWorks' editorial style, publication processes, and best practices since she helped launch the site in 1999. She's the Web editor for the Linux zone, and also serves as the tech lead for the Web editors of the technology zones. Her degrees are in Biology from the University of North Carolina in Chapel Hill, NC, and Technical writing from Rensselaer Polytechnic Institute in Troy, NY. For more info, see Gretchen's profile on My developerWorks.

Rate this article

Comments

Back to top

Table of contents

• Getting started
• Which template?
• Basic steps
• Step 1. Download the author package
• Release notes
• Step 2. Create a new template
• Step 3. Edit and validate your XML
• Step 4. Preview your content
• Composition tips
• Highlighting conventions
• Submitting your article, knowledge path, or tutorial to developerWorks
• Download
• Resources
• About the authors
• Comments

Dig deeper into XML on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers