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.
Create your content by following these steps:
- Download the author package and unzip the file.
- Create a folder and XML template for your content using a script from the package.
- Edit the XML template to add your content, then validate that XML against the schema and correct any errors.
- 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).
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.
- 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.
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
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.xsdto 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".
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
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
|Ampersand (&)||& (Always code ampersands as & — even in URLs.)|
|Left angle bracket, or less-than sign (<)||<|
|m-dash (—)||<mdash />|
|Quotation mark (")||" (In text, use the keyboard quote, but to include a quotation mark in an XML element, use ")|
|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 (>)||>|
|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
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.
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.
|IBM developerWorks author package, V7.0||author-package-V7.0_20140912.zip||1597KB|
- "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, or another OpenDocument editor, we also offer Word and OpenDocument templates for your use.
- "Illustrating your content for developerWorks: How to create effective graphics" (developerWorks, April 2010): Get detailed guidelines and tips on creating and submitting graphics for your content.
- developerWorks author guidelines and editorial policy: Learn more about our editorial policy and peek at each developerWorks editor's content wish list.
- 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 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.
- Content submission form: Submit an article 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 area you're interested in.
- developerWorks Community: Connect with other developerWorks users while exploring the developer-driven blogs, forums, groups, and wikis.
Dig deeper into XML on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Keep up with the best and latest technical info to help you tackle your development challenges.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.