Authoring with the developerWorks XML templates

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

Welcome, authors! This article shows how to prepare technical content for publication on the developerWorks site. The steps are simple. You download our XML-based template, fill in the template using any validating XML editor or your preferred Microsoft Windows or Linux text editor, check it to ensure it follows the tagging structure as defined in the developerWorks schema, and preview your content. Tips for composing your content and submitting it to the developerWorks staff are also included.

Important note! The developerWorks team is updating the Linux interface for authoring using XML templates. In the interim, Linux users should use our OpenDocument templates to create content. See the companion article, "Authoring with the developerWorks Word and OpenDocument templates."

John Holtman (holtman@us.ibm.com), developerWorks community and tools support, IBM

author photo - john holtmanJohn 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.



Gretchen Moore (gemoore@us.ibm.com), developerWorks web editor, IBM

author photo - Gretchen MooreAs 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.



Jack Pizzolato, developerWorks Software Engineer, IBM

Jack Pizzolato has been a member of the developerWorks team since the site was launched in 1999. His responsibilities include web user interface design and development and XML/XSLT development. He also supports the website's authoring and editing tools. Jack has an undergraduate degree from the University of Notre Dame in South Bend, IN, an M.A. in Journalism from the University of Florida in Gainesville, FL, and an M.S. in Computer Communications from Pace University in Westchester County, NY.



Tom Coppedge (tcoppedg@us.ibm.com), developerWorks Software Engineer, IBM

Tom Coppedge has been a member of the developerWorks design team since the site was launched in 1999. Tom's focus includes XML & XSLT strategy, information architecture, content management, and site design. He joined IBM in 1988 after receiving a degree in Information Systems & Operations Management from the University of North Carolina at Greensboro.



07 July 2014 (First published 10 February 2005)

Also available in Vietnamese Spanish

Looking for Word or OpenDocument templates rather than XML templates?

If you prefer to compose your content in Microsoft Word, OpenOffice.org Writer, or another OpenDocument editor, we also offer Word and OpenDocument templates for your use. See the companion article, "Authoring with the developerWorks Word and OpenDocument 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 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.

Content is published on developerWorks in HTML format, but is 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.

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.


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

Step 1. Download the author package

Download the author-package zip file and place it in a suitable location (for example, C:\ on Windows). 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.

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-7.0.xsd. (7.0 is the level of the developerWorks schema at the time of this writing.)
  • templates—contains the classic and rich article templates supported by this authoring package.
  • tools—contains some simple tools to help you set up and validate a new article.
  • 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: 7.0/en_US/dw-document-html-worldwide-7.0.xsl for worldwide (English) or 7.0/ja_JP/dw-document-html-japan-7.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 Windows (including Windows 7). If you need help with editing the templates using an operating system other than Windows, please contact your developerWorks editor.


Release notes

This release enables you to build an article in two formats: classic and rich. Your developerWorks editor will recommend a format to use for the particular type of content you are developing.

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

All content uses the same primary schema (xsd) file, dw-document-7.0.xsd. However, the content uses a stylesheet appropriate to the local site for which the article is being written. For example, 7.0/en_US/dw-document-html-worldwide-7.0.xsl is used for English-language content for the developerWorks worldwide site, while 7.0/ja_JP/dw-document-html-japan-7.0.xsl is used for the Japanese local site.


Step 2. Create a new template

In this step, you'll set up your own copy of the content 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

Begin in the developerworks directory.

  • If you have been asked to create an article using the classic format, double-click new-article.vbs to create the article. You may choose any valid name as your folder name; the default is my-article-classic.
  • If you have been asked to create an article using the rich format, double-click new-article-rich.vbs to create the article. You may choose any valid name as your folder name; the default is my-article-rich.
Figure 1. Creating and naming a new article on Windows
Screen capture of the dialog that appears when you click new-article.vbs to create and name a new article on Windows

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


Step 3. Edit, validate, and preview 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. 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 content 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. The Notepad++ editor also provides a plug-in to enable you to validate XML content. 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\7.0\dw-document-7.0.xsd to something like C:\developerworks\schema\7.0\dw-document-7.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 an 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) 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.

Previewing your content

You can preview your content 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 content, focus on the text 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 folder. Open index.html with a browser. More detailed instructions on using these scripts are in "Using the developerWorks XML validation tools".


Composition tips

New to XML markup?

Like all XML documents, the XML templates in the author package follow these rules:

  • XML tags usually come in a pair: an opening tag and a matching closing tag. For example, <title> and </title> are the opening and closing tags for your article title.
  • Your content goes between the opening and closing tags, as in <title>Groovy's growth spurt</title>.
  • An exception to the tag pairs is a self-closing tag such as a line break (<br />) or an image tag (<img />), where a single tag serves as both opening and closing tag; in this case, the tag ends with />.
  • XML tags (the strings between < and >) are case-sensitive and the opening and closing tags must match exactly. <Aacute /> and <aacute /> are two different elements. Most elements that you will use in developerworks articles are in lowercase.
  • Comment lines are surrounded with <!-- and -->.

The XML files that you generate in Step 2 are your best source for comprehensive tips on developing your content. 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 content:
    • There are two different code elements within the article template: <code-listing> and <code>. Use the <code-listing> element to set your code sample apart from surrounding text. If you want to put a command within the paragraph text (inline code), use the <code> element.
    • For an article in the classic format, the maximum code line length is 105 characters, INCLUDING blank spaces. The template has a sample with a ruler line to help you. For an article in the rich format, the maximum code line length is 72 characters, INCLUDING blank spaces.
    • 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 content.
    • Avoid hardcoding blank spaces or tabs at the end of a line of sample code as these are included in the 105 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. Articles in the classic format have a "Download" section for sample code. When providing downloadable sample code for the "Download" section, zip the code up and send the ZIP file to your editor separately. Your editor will be responsible for ensuring that the download file works correctly within the article.
  • Artwork. 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.
  • 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 content 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 content. 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 content for developerWorks."
  • Special characters. Code special characters as shown in Table 1.
Table 1. Special characters
CharacterXML coding
Ampersand (&)&amp; (Always code ampersands as &amp; — even in URLs.)
Apostrophe (')&apos;
Left angle bracket, or less-than sign (<)&lt;
m-dash (—)<mdash />
Quotation mark (")&quot; (In text, use the keyboard quote, but to include a quotation mark in an XML element, use &quot;)
Registered trademark (®)<reg/> (Authors can, but don't need to, insert trademark symbols; the developerWorks editorial staff will take care of trademarks.)
Right angle bracket, or greater-than sign (>)&gt;
Trademark (™)<trade/> (Authors can, but don't need to, insert trademark symbols; the developerWorks editorial staff will take care of trademarks.)

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

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

You would code the following in the XML template:

&lt;TABLE border="0" width="100%"&gt;


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? The developerWorks editorial style guide shows the highlighting conventions recommended for developerWorks content.


Submitting your content to developerWorks

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

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


Acknowledgment

The developerWorks staff would like to acknowledge the tremendous contribution of Ian Shields to the tools described in this article. Ian is a former member of the developerWorks team and a long-time contributor to the Linux zone on developerWorks.


Download

DescriptionNameSize
IBM developerWorks author package, V7.0author-package-V7.0_20140627.zip1177KB

Resources

Learn

Get products and technologies

  • Microsoft's XML Parser (MSXML) Version 4 or Version 6: To use the dw-transform.vbs script to transform your content, 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).
  • 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.
  • Notepad++: Learn about this free source code editor and Notepad replacement that runs in the MS Windows environment. After installing Notepad++, you can use the Plugin Manager to install XML tools to validate your XML file.
  • "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, or use a product in a cloud environment.

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=90785
ArticleTitle=Authoring with the developerWorks XML templates
publish-date=07072014