 | Level: Introductory developerWorks WebSphere Editorial Team (ramaker@us.ibm.com), Content Editors, IBM
25 Jan 2006
Updated 27 Mar 2008 This article walks you through the process of submitting an article idea to
the developerWorks WebSphere team, writing the article, and getting it published on
developerWorks WebSphere. You'll learn about the kinds of articles we're looking
for, our style and formatting guidelines, how to submit your article draft, and how
we pay for articles. We'll also cover important topics such as plagiarism and
copyright information.
Decide what to write
about
Our goal for developerWorks WebSphere is to tap into the technical user
communities and to publish articles and tips that directly meet their needs. Our
content describes concepts or tasks that are not ordinarily described in depth (or
at all) in the product documentation. We want to explain how to apply WebSphere
technology to solve real-world problems.
developerWorks WebSphere publishes tips, overviews, articles, and tutorials.
We're interested in the following types of technical articles:
We're looking for content that:
- Contains technical how-to information about one or more WebSphere products.
- Provides significant educational value for current or potential IBM customers.
- Describes and shows how to use current technology
- Fills a customer need, for example, walks through how to solve a realistic
business problem.
- Does not duplicate information already available in product documentation,
other articles, redbooks or other sources. For example, there is usually already
plenty of documentation that explains how to install software, so you probably
don't need to put this in your article.
- Is clear, organized, unambiguous, and states and meets objectives.
Submit your idea
You can submit content ideas and proposals using the
Content Submission form.
Your proposal should include:
- A brief explanation of what you want to write. Your proposal should have an
appropriate topic and shouldn't duplicate another piece of content already
published on developerWorks.
- The reasons why you think other readers will benefit from your article or
tip and why you're the right person to write it (explain your expertise).
- An outline listing each topic you'll cover. This helps you develop your
thinking and lets us know exactly what you plan to cover.
- Your contact information (including email address), so that we can contact
you.
- Optionally, any sample code that may accompany the content.
- You may include a draft of your article if you have one completed.
We need to know the origin of your article, whether it was written to fulfill a
customer need, is part of a project, or whether you prepared it on your own. This
information is used to determine any publishing liabilities and whether the
article qualifies for payment.
If we're interested in your proposal, we'll contact you by email. We may ask to
review a partial or complete draft of your work before accepting it. This work is
done on speculation, meaning that we reserve the right to refuse the draft if we
determine that it either doesn't suit our content needs or isn't of publishable
quality. Acceptance of a proposal does not constitute acceptance of the article.
If we accept the draft, we'll work with you to edit the content, to ensure that
it's technically reviewed by appropriate subject matter experts, to schedule the
article for publication, and to assign a deadline for your final draft.
For more information on what kind of content we're looking for and how to improve
the chances of getting your proposal accepted, see
So,
you want to write articles for developerWorks?.
Write your article
Once you've submitted your topic and we've accepted it for possible publication,
you're ready to begin writing the article. Following are some guidelines that will
help you in developing your article for developerWorks WebSphere:
- Verify that all products and product functions that you reference in your
article are generally available. Use official product names, versions, and
releases; for example, WebSphere Application Server Version 6. If a product is
not yet available, we'll work with you to time publication of the article after
the product announcement.
- Cover your topic thoroughly and in a logical sequence. Include only relevant
information and exclude extraneous details.
- Write in a professional and positive tone, and in a style appropriate for your
audience. A casual and conversational tone is acceptable and appropriate, but
overly informal language and disparaging or heavily opinionated comments are
unacceptable.
- Use active voice.
- Write descriptive headings for sections. Aside from "Introduction" and
"Conclusion", make your headings specific and concrete. Avoid headings devoid of
technical content such as "Getting started," "Next steps," "Considerations," and
so on.
- List all task steps, if any, clearly and in numbered lists, rather than
burying them in paragraphs of text. This is a common problem.
- Explicitly identify all IBM products that your article applies to, including
full product name, edition, and version. For legal reasons, we cannot refer to
IBM products by commonly used acronyms, such as WSAD, WAS, WEMP, WPS, or RAD.
Some product names have approved short names, which can be used after the first
occurrence, such as "WebSphere Studio Application Developer (hereafter called
Application Developer)". Your content editor, brand manager, or IPL attorney
will help you determine whether an approved short name exists for your product.
- Define technical terms and avoid jargon.
- Define acronyms on first occurrence if they're likely to be unfamiliar to your
intended audience (for example, "message-driven beans (MDBs)").
- Avoid using special characters (such as en-dash, em-dash, ellipses, etc.),
wherever possible.
- Don't use single or double quotes (exception: use quotation marks for lengthy
window titles that are not easily distinguishable from surrounding text).
- Don't use italics (except for book titles and new words defined in the text).
- Use bold for user interface elements you click on.
- Use monospace font for examples, code snippets, text or commands the user
enters, and method and class names.
- Use plain text for window names, view names, and file names.
Originality
We don't consider content that has already been published elsewhere, including
other areas of developerWorks, third-party publications (print or Web), and
personal Web sites. We will consider simultaneous submissions, but require that
you notify us if you have submitted an idea to more than one publication at a time
for consideration. All work must be original and unique. See
Plagiarism for more information.
Graphics
When writing your content, you may want to include:
- Screen shots
- Tables
- Conceptual diagrams
- Flowcharts
- Graphs
Use graphics and screen shots judiciously. For example, it's not necessary to
include screen shots for every step in a task, but you should definitely use them
where they are useful to show complex steps or screens. We will remove any
graphics that we think are extraneous or unnecessary.
Don't use screen shots to present sample code. Screen shots may be difficult to
read, are not accessible to screen readers (and therefore, to those who are
visually impaired), and are not visible to users who view the content with
graphics turned off in their browser. Include the code in the body of the content
and refer to screen shots to illustrate what users may expect to see.
Because we rarely accept media files, we do not encourage their use in articles
and reserve the right to refuse them.
Article graphics can be no more than no more than 572 pixels wide. We will resize
or crop any graphics wider than this and format images when necessary, if you
don't have the tools to do so.
Submit all graphics with the final draft of your content. You can send them as
GIF, JPG, BMP, Photoshop (PSD), or PZD files.
Contact information
Unless requested not to, we will publish author e-mail addresses in your article.
If you do not want your e-mail address published, you must specifically request
that when you submit your article to us.
Downloads
It's a good idea to provide code samples as downloads with your articles. If you
have code samples or other downloadable information you want to include, combine
them in one or more ZIP files and submit them with your final draft.
Organize your article
The body of your article should typically include the following sections:
- An overview section that introduces the article, including:
- An interesting lead paragraph that pulls the reader in
- A brief description of the feature or task that will be covered in the
article
- A brief synopsis of what the article will cover
- Guidelines or prerequisites for the article and the assumed technical
experience of the reader
- A section that lists all system prerequisites and configuration information.
- An in-depth section that fully describes the subject, such as:
- A detailed feature description
- Benefits of this feature and how it is used
- How the feature was designed or developed (what the challenges were; how
these challenges were met)
- Associated graphics, diagrams, charts, tables, or code samples
- For tasks, one or more sections that include:
- Specific steps for completing the task. Make sure you explain the
reasons for each step.
- Appropriate screen shots, where necessary. See
Graphics for guidelines on appropriate use of
screen shots.
- A customizing section (optional), which may include:
- A description of how or why users might customize the technique to suit
their needs
- Any necessary troubleshooting information for the feature or task
- A summary that wraps up or reviews what you have just explained. Describe
what the reader has learned and how they can apply it.
- An brief biography for each author, which should include:
- Job title
- Your related experience and education. Explain what makes you a expert
on this topic
- Optionally, your hobbies or things you enjoy outside of work
- Links to related information -- especially articles published on
developerWorks, related product documentation, pertinent IBM Redbooks, and any
IBM product or marketing information.
Format your content
You can develop your articles in Lotus® WordPro or Microsoft® Word,
or in our developerWorks XML template. Do not submit PDF files. Our editors
convert all articles to XML and transform them to HTML. When your proposal is
accepted, your editor will work with you to determine the format in which they
would like to receive your article draft.
You'll find detailed instructions on how to use the developWorks XML template,
including a downloadable authoring kit, in
Authoring with the developerWorks XML templates.
A Word template for creating your article is included in the
Download section.
Submit your content
A completed draft of your article is generally due six to eight weeks before the
scheduled date of publication. When you submit your completed draft, make sure to
include the following:
- A suggested title (we reserve the right to change titles to meet our
conventions)
- A brief author biography
- The names of at least two subject matter experts who have reviewed the draft
for technical accuracy
- For IBM employees, a note from your manager indicating approval to publish the
article on developerWorks.
- All graphics in JPG or GIF format.
- All downloads in ZIP format
After you submit the completed draft, our editorial staff will carefully review
the entire package. At this time, we may rewrite sections of your draft to make it
clearer and to adjust the wording of the content to fit our style or format. Or,
we may send the draft back to you with recommendations for revision. No article on
developerWorks WebSphere is published without thorough editing and technical
review.
Once the review is complete, we'll copyedit the content and prepare it for
publication.
Even after receiving a completed draft, we reserve the right to postpone
publication or to refuse publication under the following circumstances:
- We are unable to obtain a thorough technical review of the article. This may
occur if technical reviewers are unavailable or unwilling to review a draft.
- The article content cannot be shared publicly until a later date, or we feel
that a later publication date is more appropriate due to a product's release
date.
- We discover that the content (or significant portions thereof) has been
previously published.
- The submitted draft is deemed unworkable from an editorial perspective.
- The author is unresponsive to requests for changes.
As an author, you may not agree with our editorial decisions or with the
technical review comments. In that case, you have to right to withdraw your
submission and to offer the original (unedited and unreviewed) article or tip to
another publication.
Plagiarism
We will not accept work that contains any plagiarized material, including
material taken from product documentation, IBM Redbooks, other developerWorks
articles, or any other IBM sources, even if we have accepted your content idea. If
you must borrow ideas or content from another source, you must credit the source
properly. To present someone else's work as your own is plagiarism and is in
violation of U.S. copyright law.
Upon the first offense, we'll immediately send the article back to you for
revision with the expectation that you will remove or properly accredit all
plagiarized sections. If the offense happens a second time, we'll refuse the draft
that you send and will no longer accept any work from you.
For more information about what constitutes plagiarism, see
"What is plagiarism?"
on the Plagiarism.org Web site.
Payment
We compensate both external writers and internal IBMers for their articles as
long as the work is completed on their own time, is done on a voluntary basis
above and beyond their normal responsibilities, and is not part of any directed
work effort.
We evaluate each article on an individual basis. We do not pay a flat fee for
articles nor do we pay by the word or page. Payment is based on the following
criteria:
-
Editorial quality: How well written is the draft when we receive it? We
edit, copyedit, and proofread each draft. When determining payment, we take into
account how much time and effort we were required to spend editing the document.
-
Thoroughness: Does the article offer a cursory introduction to a topic or
cover it in-depth? Typically, the more technically in-depth an article and the
more comprehensive the topic, the more the content is worth to us. Articles that
offer only an introduction to a topic often leave opportunities for other
authors to cover the same topic in more detail.
-
Skill level: We have three skill levels for articles: beginner,
intermediate, and advanced.
-
Timeliness: Is the article topic a current one? In some instances, we
publish articles tied to product releases, such as a new features article that
debuts when the product is released. We may turn down content that covers older
product releases (when newer releases are available), or we may ask an author to
consider updating an article draft to reflect a current product release.
-
Length: As mentioned earlier, we don't pay per word or per page; however,
we take into account the length of a piece when it reflects how comprehensive
the content is. Oftentimes shorter pieces can be lengthened to provide more
technical details.
-
Author responsiveness and cooperation: We will reduce payment to an
author who does not respond to edits and technical reviews in a timely and
appropriate manner.
-
Content value: Exceptional coverage of high priority topics is usually
more valuable than coverage of topics that are already covered by a variety of
sources, or for which there is little demand.
Copyright
All content published on developerWorks WebSphere are copyright protected. This
means that no part of the article or tip may be reproduced or transmitted in any
form or by any means without the prior written permission of the developerWorks
WebSphere editorial team. If we publish content that you submit, that content is a
"work made for hire," as defined in
Section 101 of the Copyright Statute;
and IBM owns the submitted content. This prohibits you from publishing the content
in any other publication.
If you have a question about our guidelines or if you have a question not
answered here, please contact
Chris
Rothemich.
Download | Description | Name | Size | Download method |
|---|
| Word template | wordtemplate.zip | 23 KB | FTP|HTTP |
|---|
Resources Learn
Get products and technologies
Discuss
-
Submission
form:
Submit your article ideas using the developerWorks submission form.
About the author | 
| | This content is brought to you by the developerWorks WebSphere editorial team:
Deborah Cottingham: WebSphere Portal zone
Jim Mann: Manager, WebSphere Voice zone
Stephanie Parkin: WebSphere Studio zone
Jim Ramaker: Managing Editor, WebSphere Business Integration zone
Chris Rothemich: WebSphere Web services zone, Wireless with WebSphere zone, High Performance On Demand Solutions zone, WebSphere partner pages
Carol Serna: WebSphere Business Integration zone
Scott Shekerow: WebSphere Developer Technical Journal, WebSphere Application Server zone, WebSphere Education, Software Services for WebSphere
Dorothy Wu: WebSphere Commerce zone, Meet the Experts, Podcasts |
Rate this page
| |
