 | Level: Introductory Editorial staff (dwinfo@us.ibm.com), developerWorks, IBM
10 Feb 2005
Updated 04 Sep 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. 04 Sep 2008: The IBM
developerWorks author package, V5.10, was
updated with a bug fix.
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.
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.
Basic steps
Create an article or tutorial by following these steps:
-
Download the author package and unzip the file.
-
Create a folder and XML template for your article or
tutorial 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 article or tutorial 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 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.
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
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.
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 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.
Figure 2. Creating and
naming a new tutorial on Linux
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.
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.
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".
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 (<) | < | | m-dash (—) | <mdash /> | | Quotation mark (") | " | | 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.
 |
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.
Table 2. Recommended highlighting
| Highlighted element | Recommended highlighting | Example |
|---|
| "Article titles" | Quotes | "Article titles" | |
Book titles
| Italics | <i>Book titles</i> |
C/C++ code
| Inline code | <code type="inline">C/C++
code</code> |
Classes
| Inline code | <code
type="inline">Classes</code> |
| Code section | <code type="section">
Code
samples
</code> |
Code snippets (less
than one line) referenced in text
| Inline code | <code type="inline">Code snippets (less than one
line) referenced in text</code> | |
Column or series names
| Italics | <i>Column or series names</i> |
Command names
| Inline code | <code type="inline">Command
names</code> | | Directory names | No highlighting | Directory names | |
Emphasis
| Italics. For example: "Use that to introduce a restrictive
clause. Do not type over .." | Use <i>that</i> to introduce a
restrictive clause. Do <i>not</i> type
over .. |
Exception names
| Inline code | <code type="inline">Exception
names</code> | | File names | No highlighting | File names |
Function
calls
| Inline code | <code type="inline">Function
calls</code> | |
GUI controls
| Bold. For example: "On the Installation menu, click Install a
new feature > Finish." | On the Installation menu, click <b>Install a new
feature</b> >
<b>Finish</b>. |
HTML tags or
portions
| Inline code | <code type="inline">HTML tags or
portions</code> |
Interfaces
| Inline code | <code
type="inline">Interfaces</code> |
Keywords (such as
static)
| Inline code | <code type="inline"> Keywords (such as
static)</code> | |
Magazine titles
| Italics. For example: "See the related article in
LinuxToday ..."." | See the related article in
<i>LinuxToday</i> ... |
Message text or
prompts addressed to the user
| Inline code | <code type="inline">Message text or prompts
addressed to the user</code> |
Methods
| Inline code | <code
type="inline">Methods</code> |
Objects
| Inline code | <code
type="inline">Objects</code> | | Path names | No highlighting | Path names | |
Terms defined in context
| Italics | <i>Terms defined in context</i> |
Text entered by
users
| Inline code | <code type="inline">Text entered by
users</code> | | "Tutorial titles" | Quotes | "Tutorial titles" |
Types (such
as int or long)
| Inline code | <code type="inline">Types (such as int or
long)</code> | | URLs | No highlighting | URLs | |
Variables
| Italics. For example: "... where myname represents your
user ID..." | ... where <i>myname</i> represents
your user ID... |
XML tags or
portions
| Inline code | <code type="inline">XML tags or
portions</code> |
|
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.
Download | Description | Name | Size | Download method |
|---|
| IBM developerWorks author package, V5.10 | author-package-V5.10_20080903.zip | 392KB | HTTP |
|---|
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 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.
Discuss
About the author | | | This content is brought to you by the developerWorks editorial staff. |
Rate this page
| |
