Jazz.net Article Authoring Guidelines

First Steps

First, understand what types of articles we publish in the jazz.net library:

• how–to articles that provide a solution to a specific problem
• descriptions of how you've been successful using Jazz products
• lessons learned (e.g. how I got ABC working with XYZ)

If your idea fits into one of those categories, your next step is to search the jazz.net library for existing articles that cover your topic. There is a chance that someone has already had the same great idea for an article.

Before you start writing your article, draft a simple abstract that describes your topic and why it's important. Make it clear how readers will benefit from the contents.

Finally, ask some of your peers to review your idea. Do they see the benefit?

Style and formatting guidelines

While the most important criteria for technical content in the Jazz.net library are accuracy, relevance, and usefulness, we also value clarity, quality, and consistency.

When you're ready to begin the writing process, follow these style guidelines to ensure a smooth submission and review process.

Template

Submit your article using this html template. Using the template helps us publish your article sooner. It allows the editors to concentrate on the content of your article rather than its formatting.

Writing style and general guidelines

• Your article must be your original work. If any of the content (including code snippets, graphics, or any text) comes from another source, you must obtain permission from the owner to use it and credit the source in your article.
• Keep the content interesting and lively. After all, you probably wouldn't want to read a boring article! A casual, conversational tone is appropriate, but be professional. Highly opinionated or disparaging comments are not appropriate.
• Be clear, unambiguous, and practical. Clearly define terms that might be unfamiliar to the reader.
• Aim for maximal content with minimum words. Forty page articles are better published as paperback novels. Three to five pages is a general guideline.
• Use a natural, active voice (rather than passive). Avoid long sentences and sentences with complex structure (25 or more words).
• Try to use the pronouns "you" and "your" to personalize for the reader as opposed to "the user" or "the user's".
• Use common industry terminology. Avoid jargon.
• Organize your article with descriptive section headings.
• Add a short author biography that includes your job title, company, and relevant experience and education.

Formatting

• Steps and instructions:
• Use the imperative voice for instructions. Example: 1. Click Save and close the window.
• Use HTML ordered lists for procedures and unordered lists for non–procedural lists.
• Nest lists to clarify a procedure.
• Screenshots:
• Include screenshots where a visual representation is necessary or helpful.
• Crop screenshots to show only the necessary elements.
• Make the maximum width 640 pixels.
• Include captions and alt tags
• Highlighting conventions:
• Make UI elements (check boxes, radio buttons, menu items) bold. Example: Select the Auto-deliver changes check box.
• Make file names and directories: monospaced. Example: Edit the server-startup.bat file found in the C:/Jazz/server directory.
• Make code snippets and blocks: monospaced ( <tt> for snippets, blocks go inside a <pre>).
• Make menu cascades Bold > Bold. Example: From the main menu, select File > New > Change set.
• Acronyms and abbreviations:
• Spell out technical acronyms on first use. Include the acronym in parentheses directly after.
• Avoid abbreviations (Latin, text message). Use common industry terminology (avoid jargon) and always define acronyms on their first use.
• Product name usage:
• Spell out the full product name on the first occurrence. Example: IBM Rational Team Concert
• After the first occurrence, use the product name only if it adds clarity to the situation that you are describing.
• Titles and headings:
• Make your article title as descriptive as possible. Example: Best practices for employing Scrum methodologies in Rational Team Concert 2.0.0.2
• Use sentence style capitalization for titles and headings

Packaging your article

• Create a folder for your article. Include the html (using the provided template) and subfolders for images and code.
• If you have code snippets, have your article link to a compressed archive file containing a plug-in with the code.
• Compress the top-level folder into a single archive file. Confirm the file is smaller than 10 MB.

The submission process

Submit your article via E-mail. Provide your name, article title, article abstract, contact E-mail address, company name, and your article archive.

A jazz.net articles editor will review your content and provide any initial feedback to you via E-mail. Once your article is accepted, you may have some refinements to make based on editorial and technical reviews. Feedback is a good thing, and most articles require a couple of drafts before they are finalized and ready for publish.

Before the article is posted on jazz.net and linked into the main content, the editors will ask you to certify that the content is all original and/or can legally be published.

© Copyright 2011 IBM Corporation