Authoring with the developerWorks XML templates

Document options PDF - Fits A4 and Letter 109KB (16 pages) Get Adobe® Reader® Document options requiring JavaScript are not displayed Sample code Rate this page Help us improve this content

Level: Introductory

Editorial staff (dwinfo@us.ibm.com), developerWorks, IBM　

10 Feb 2005
Updated 15 Jul 2008

Welcome, authors! This article shows you how to prepare English-language technical articles and tutorials for publication on the worldwide developerWorks site. The steps are simple. You download our XML-based template for articles or for tutorials, 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 article or tutorial. Tips for composing your content and submitting it to the developerWorks staff are also included.

Looking for Word or Writer templates rather than XML templates? If you prefer to compose your content in Microsoft Word or OpenOffice.org Writer, we also offer Word and Writer templates for your use. See the companion article, "Authoring with the developerWorks Word and Writer 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, you can use our content submission form to submit your idea.

Articles and tutorials are published on developerWorks in HTML format, but are written using XML (Extensible Markup Language) format. Prior to publication, the XML source of each article and tutorial 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 article and tutorial 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.

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 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 and unzip the file.
2. Create a folder and XML template for your article or tutorial 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 article or tutorial 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 in /opt/ibm (if you use the tarball). 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).

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-5.10.xsd. (5.10 is the level of the developerWorks schema at the time of this writing.)
• tools -- contains two templates (template-dw-article-5.10.xml and template-dw-tutorial-5.10.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 article or tutorial.
• xsl -- contains the primary stylesheet file dw-document-html-5.10.xsl and several secondary stylesheets.

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.

On March 21, 2008, the version 5.10 schema and stylesheets were released to authors. The 5.10 schema and stylesheets include internal changes for best use of leading Web technologies for social tagging and data management. The external changes of interest to authors are minimal, and reflected in the updated templates for articles and tutorials:

• Code listings now allow mixed highlighting (bold, italics, and plain text) on a single line without adding an unexpected line break.
• Code listings also support multi-line highlighting with a single pair of tags (bold or italics).
• Component, Grid, Systems, Unicode, Wireless, and Workplace are no longer available as a content area.

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

Articles and tutorials use the same primary schema (xsd file) and primary stylesheet (xsl file):

• Primary schema: dw-document-5.10.xsd
• Primary stylesheet: dw-document-html-5.10.xsl

Back to top

Step 2. Create a new template

In this step you'll set up your own copy of the article 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 or new-tutorial.vbs to create a tutorial. You may choose any valid name as your folder name. The defaults are my-article 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 article or tutorial template (index.xml) and a validation and transformation script (dw-transform.vbs).

Using Linux

Use the new-article.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 in which you can enter your new project's name.You can choose any valid name. The defaults are my-article 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 article or tutorial template (index.xml) and a validation and transformation script (dw-transform.sh).

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. 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, the references to the schema and stylesheet files are relative to your tutorial or article directory. You may need to change the references (..\schema\5.10\dw-document-5.10.xsd and ..\xsl\5.10\dw-document-html-5.10.xsl) to absolute references such as C:\developerworks\schema\5.10\dw-document-5.10.xsd. In some editors, you may have to specify the location of these files through other configuration means.
• If you transform your tutorial or article 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 article or tutorial

You can preview your article 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

New to XML markup? Like all XML documents, the XML templates in the author package follow these rules: XML tags (the strings between < and >) are in lowercase. XML tags usually come in a pair: a start tag and a matching end tag. For example, <title> and </title> are the start and end tags for your article or tutorial title. Your content goes between the tags, as in <title>Groovy's growth spurt</title>. An exception to the tag pairs is a tag such as a line break (<br />) or an image tag (<img />), where a single tag serves as both start and end; in this case, the tag ends with />. Comment lines are surrounded with <!-- and -->.

The XML templates are your best source for comprehensive tips on developing your article or tutorial. Extensive comments in the templates (template-dw-article-5.10.xml and template-dw-tutorial-5.10.xml in the tools directory) guide you through every aspect of coding your article or tutorial. Here are some other tips you might find helpful:

• Composing in Microsoft Word or OpenOffice Writer?

  You can use the Word or Writer template, instead of the XML template; find complete details in "Authoring with the developerWorks Word and Writer 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 Writer 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. Also, if your Word or Writer document has embedded images, don't worry about extracting them; simply forward the Word or Writer document to your developerWorks editor, and our team of visual designers will extract and refine the images. And finally, if your Word or Writer 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!

• End tags. Remember to use end 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. Avoid span tags, code font tags, CDATA tags, and font classes.
  
  
• Code listings. When including listings of sample code inline in your article or tutorial:
  
  
• Maximum line length is 90 characters, INCLUDING blank spaces.
  
  
• Maximum 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.
  
  
• 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 bold (<b> and </b>) 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 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 how to more about how to create and deliver effective graphics.
  
  
• Special characters. Code special characters as follows (do not use CDATA tags):
  
  
  

  Table 1. Special characters

  Character	XML coding
  Ampersand (&)	& (Always code ampersands as & — even in URLs.)
  Apostrophe (')	'
  Greater than sign (>)	>
  Less than sign (<)	&lt;
  m-dash (—)	<mdash />
  Quotation mark (")	&quot;
  Registered trademark (®)	<reg/> (Authors can, but don't need to, insert trademark symbols; the developerWorks editorial staff will take care of trademarks.)
  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:
  
  <TABLE border="0" width="100%">

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

Back to top

Highlighting conventions

Not sure what needs <code type="inline"> tagging and what doesn't? 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.

Code samples

Back to top

Submitting your article or tutorial to developerWorks

Once you've finished your masterpiece, you're ready to send it to your developerWorks editor. E-mail the XML 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: 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

• "Using the developerWorks XML validation tools" (developerWorks, March 2008): 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 Writer templates" (developerWorks, March 2008): If, instead of using the XML templates, you prefer to compose your content in Microsoft Word or OpenOffice.org Writer, we also offer Word and Writer templates for your use.
  
  
• "Illustrating your article or tutorial for developerWorks: How to create effective graphics" (developerWorks, January 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.
  
  

• 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® Web Developer for WebSphere® Software V6.0: Download a 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 development with Eclipse" (developerWorks, April 2003): Create XML documents using the Eclipse platform with plug-ins such as Bocaloco Software's XMLBuddy.
  
  

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

About the author

		This content is brought to you by the developerWorks editorial staff.

Rate this page

Please take a moment to complete this form to help us better serve you. Did the information help you to achieve your goal? Yes No Don't know   Please provide us with comments to help improve this page:   How useful is the information? 1 2 3 4 5 Not useful Extremely useful

Share this.... Digg this story del.icio.us Slashdot it!

Back to top