Write for iSeries NEWS

Our most valuable articles come from technical professionals who write from their own experiences. Through the network iSeries NEWS provides, these computing practitioners offer their fellow professionals field-tested techniques and practices that have helped them in their work. If you're a seasoned writer with many publication credits, great! But even if you've never before written for publication, your professional experience is a valuable resource; we can help you share it with our readers.

How to Reach Us

• Direct your questions about our articles-acquisitions process to Lori Piotrowski, acquisitions editor, (970/203-2824).
• Send proposals, outlines, articles, and utilities to Lori Piotrowski, (970/203-2824).

We're Glad You Asked

When you have an idea for an article, please let us know. An e-mail message, letter, or fax to us sketching what you intend helps ensure that the article will address a topic we want to cover. And it prevents conflicts when we have already accepted an article by another author on that or a closely related topic.

Your proposal should include a brief abstract that describes the article's topic, scope, and audience; an outline showing the organization and major points you will address; and a short bio highlighting your technical background. Approval of your abstracts and outlines will greatly improve the odds that your articles will be accepted without extensive revision. The abstract should include:

1. Your name, address, phone number, fax number, and e-mail address
2. The working title of the article
3. The audience (technical novices, experienced professionals, technical managers, or a combination)
4. A few sentences stating the article's main focus and key supporting points, including a statement of the article's benefits to the reader
5. A list of the examples (code, illustrations, figures, and so forth) you plan to use to support your points
6. The date you can have the finished article to us

The article outline should be sufficiently detailed that a technical reviewer will clearly understand what you intend to cover. For example, if one subtopic will involve a discussion of various approaches, list those approaches.

If you have a number of potential article topics in mind and want guidance on which to pursue first, send us a letter or fax listing your proposed topics with a few sentences describing each. Please also include a short bio. We'll get back to you with our priorities and suggestions.

Getting Started

One easy way to begin is to send us a brief technical tip (300 to 1,000 words) for our Tech Corner department. We also look for useful, well-documented programs to publish in our Load'n'Go department. If you've developed a utility you'd like to share — but you just don't have the time or inclination to write an accompanying article — consider just submitting the code. We look for efficient algorithms with no bugs, and we prefer adherence to accepted standards (e.g., structured code). We like CL code to conform to iSeries NEWS's style guidelines, published in July 1999 (page 66). See also The Essential RPG IV Style Guide, published in June 1998 (page 64) for RPG style preferences. We have handouts listing Cobol style preferences; let us know if you'd like us to mail or fax them to you. Your program should be submitted electronically via e-mail or on diskette accompanied by a hard copy, a brief explanation (1,000 to 1,500 words) of the utility's benefits, a description of how it works, and suggestions for operating.

If you'd rather share your opinion than your code, consider contributing to our guest editorial column, Dialog Box. We need well-reasoned, thought-provoking pieces (1,000 to 2,000 words) about issues of interest to the AS/400 programming community (programming practices, IS management concerns, new technologies, future trends, etc.) or the larger computer industry (computer-related social, environmental, economic, and political issues). You may submit responses to previously published opinions as well as editorials covering new ground.

Feature-length Attractions

Maybe you have an idea for a feature article (1,800 words) that you're eager to tackle. If so, you have a variety of formats to choose from. iSeries NEWS publishes technical tutorials and "how-to" articles, technical management advice, discussions of software engineering principles and programming fundamentals, analyses of news and trends, book reviews, case studies, and product reviews (see "Writing Case Studies, Product Reviews, and Demo Booths for iSeries NEWS"). Thorough analysis of a few back issues of the magazine will help you better understand what we're looking for in each of these types of articles. Regardless of the format you choose, before you invest a lot of time and energy in writing, you should first contact us to make certain we can use your topic.

Eight Keys to a Successful NEWS Article

If you've ever coached a computer operator through error recovery over the telephone, you have some idea of what it's like to write a technical article for iSeries NEWS. You can't sit down at the keyboard with your readers and show them what your article is trying to say. You have only the English language to convey your message. To get your point across successfully, you should take extra pains to be clear, concise, and complete.

1. The first step when writing your article is to choose your audience. iSeries NEWS uses a mix of articles to serve its readers, who range from technical novices to experienced technical professionals (including programmers, analysts, engineers, operators, consultants, and IS managers). Knowing your audience helps you decide what content to include, what level of detail to use, and what tone to select when presenting your information.
2. Next, you need to organize the presentation of your information. A detailed outline is vital to keeping your article focused, with every section and each example clearly contributing to your article's purpose. Your piece should have a clearly defined introduction, body, and conclusion.
3. The introduction introduces a problem and its solution. You should be certain to specify clearly the benefits of reading the article. Promise the reader that good things are coming, and orient the reader to expect those good things within a certain framework. And if there are conditions under which your technique is not appropriate, let the reader know that, too.
4. In the body of your article, you should describe in detail your solution to the problem stated in the introduction. The text should be organized in a way that is interesting yet easy to understand. For instance, a "how-to" article might discuss the most general information first and then present information about tasks in the sequence in which the reader must perform them. A case study might present information and tips in chronological order. Whatever order of presentation you choose, be sure that it is logical and fits your material.
5. The conclusion returns to the promise made in the introduction. Now that the reader has seen and evaluated the information you've presented, he or she will be ready to grasp all its implications. This is your chance to summarize the essential points you've made. Your work may suggest important future trends; let the reader know what these trends are and suggest how he or she can take advantage of them. Motivate the reader to use your information in the real world.
6. A key point about writing for iSeries NEWS: Please be as specific as possible throughout your text. Information processing is a business filled with abstract ideas. To communicate those ideas effectively, you should provide plenty of accurate technical detail and illustrate your points with examples, figures, screen captures, and program code — clearly labeled and carefully referenced in the text. We can't overemphasize that it's better to include too much well-organized detail rather than risk including too little.
7. If your article includes executable code, make certain the code works — not only under normal circumstances, but under abnormal conditions, too. For example, if your program expects an object name in its first parameter, make sure the program can handle object names of all types, invalid object names, and even a missing object name.
8. It's important to reread and revise your text. Prune away unnecessary words; fill in any gaps. Have a fellow professional read your article to let you know what's clear and what's not, where an example might emphasize a point, or where a transition is needed to clarify the article's direction. His or her suggestions can help you strengthen the article. You should also make certain you have dealt with any feedback you received from a review of your abstract, outline, or earlier draft by iSeries NEWS's technical reviewers. When you have your article in topnotch shape (and your code is tested and debugged), it's time for . . .

The Big Send-Off

For reviewing and editing efficiency, we ask you to submit both a hard copy and an electronic version of your article and accompanying code. The hard copy may be mailed or faxed (attention: iSeries NEWS acquisitions assistant); the electronic version may be sent on a PC or Mac diskette or transmitted via CompuServe or the Internet. Abstracts and outlines need not be sent electronically. Photographs and artwork that illustrate your article are welcome. If you want us to return your material, you should enclose a stamped, self-addressed envelope. Please note that because of the time and resources we invest in article reviews, we cannot consider multiple submissions — that is, articles you simultaneously send to us and to other publications.

For magnetic media, we prefer MS Word or WordPerfect word-processing text files. Other word-processing files must be converted to ASCII. All diskettes should be clearly labeled with your name, whether they are for a PC or Macintosh, and the type of files (i.e., WordPerfect, Word, or ASCII). Do not use any fancy desktop-publishing features such as multiple type styles, two-column format, or embedded graphics figures. All figures (fully referenced) should be in a separate file. We can accommodate a number of PC/Mac screen-capture formats; just let us know what you plan.

When you submit a utility or an article with executable source code, it is particularly important to provide the program code, associated CL code, screen format members, and your test data electronically so our technical editors can test your program submissions on their own systems. Diskette labels should include your name, address, telephone number, a description of the diskette's contents, and a reference to your article's working title (if different from the content of the diskette). Along with the electronic version, we require a hard-copy listing of all executable code.

To submit electronically, e-mail a cover note to Lori Piotrowski and attach the article file. Our e-mail address is editors@iseriesnetwork.com. For more information and detailed instructions for transmission, please call (970) 203-2824 or (800) 621-1544 and ask for Lori Piotrowski.

The Final Steps

We'll let you know by e-mail, phone, or fax when we receive your abstract or article. If you don't get this acknowledgment, by all means, give us a call. All submissions we receive are routed to a minimum of three reviewers for comment and recommendation. This process takes four to six weeks. Please be patient.

If your article receives a positive review from technical and manuscript editors, we will accept it and notify you by mail, e-mail, fax, or phone. But before we can publish your article, we must obtain the necessary publication rights. You will receive a letter with a copyright form that you must return with your signature. Although we usually purchase all rights, we will reassign noncompetitive publishing rights to the author on request. You should ask us to do so if you plan to use the material again in presentations, books, films, or other forms of publication. Because of our Web site, we retain the rights to use the material in electronic form, and — because of our international editions — we cannot restrict our rights to North America.

Once we schedule an article for a specific issue, we edit it carefully for clarity, accuracy, and editorial style. At iSeries NEWS, editing is an interactive process that involves close communication with the author — especially when highly technical material is revised. Please be patient with your editor and provide the explanations the readers will need. We will be careful with your material, and you will have a chance to see the edited article before it's sent to our printing press.

A few weeks after your article appears in the magazine, you should get a check from us in the mail. We pay 17¢ per published word for beginning authors, 50¢ per line for code, and $10 each for illustrations, diagrams, and screen captures. Word rates for experienced authors are negotiable. Product reviewers receive an additional $300 for testing a product. We pay a flat rate of $200 for utilities submitted without text. Rates for articles, utilities, and tips published on our Web site are negotiable. Finally, don't underestimate the other rewards. You'll feel the thrill of seeing your words in print and have the satisfaction of helping your fellow professionals.

Each day's mail includes at least one announcement of a new or improved AS/400 software solution we think iSeries NEWS readers would like to know more about. We can't test them all, and our lab is not always the best place to test them, anyway. So, we encourage you to share your knowledge about midrange products gained through everyday business use. You can write a case study about a product that your company has put into regular production, or you can obtain a copy of a product from a vendor specifically for the purpose of testing it for a product review. (Vendors who want to write about their own products should submit articles for our Demo Booth department.)

The introduction to a case study should set the scene and provide a little background about your company, your IS shop, and the situation/problem for which the product or combination of products supplies a solution. Identify the products and vendors. Describe briefly the products' functions and why you chose them over other possible solutions.

The body of your case study should provide more detail about your experience. When you're writing about a subset of a product (e.g., a module of a human resources application package), describe the module's integration with other parts of the overall application. For utilities that automate a part of a process (e.g., a debugger), describe how you use the utility with other tools. Talk about what was involved in implementing the solution. How long was the learning curve? What mistakes did you make? What serious problems did you encounter? What workarounds did you devise? What innovative uses did you put the product to? What productivity, quality, or customer service gains did you achieve?

Your conclusion should provide an overall assessment of the solution's value to your organization. You might also want to share your wish list for future product enhancements. Your text should be accompanied by appropriate illustrations, such as screen captures, report samples, and diagrams. For an example of a vendor-submitted case study, click here.

If you prefer a product review to a case study, contact us first by phone or fax. If we are interested in a review of the product you have in mind, we will work with the vendor to obtain the product for you. Keep in mind, though, that writing a formal review of a product requires more rigor (and effort!) than a case study. You can't get a product and just play with it for an afternoon. You have to test the product off and on for as long as it takes to produce an effective and informed product review.

Use the product from the perspective of the "average" user the vendor is targeting. If that user is technically advanced, use the product from that perspective. If the product is aimed at occasional computer users, be more aware of the learning curve. Don't limit your usage to the vendor's tutorial; try some of your own data or applications. And don't accept what you learn from marketing literature, manuals, and word of mouth at face value. Test it!

The job of a reviewer is to see not only that a product works but how well it works. This means trying to make the errors a user might make in using the product, such as entering the wrong input, pressing the wrong command key, specifying nonexistent libraries or files, or entering numeric data in an alpha-only file (and vice versa). To simulate a power outage, try canceling the program abnormally, and note how well it recovers.

If you are reviewing a single product, discuss how similar offerings from IBM and major third-party vendors work (include important workstation-based alternatives, if any). If you are reviewing two or more similar products, compare them feature by feature, benchmark by benchmark, and put this information in figures. This information is as important (if not more important) than the text of the article because readers often look at the comparison charts first.

The introduction to a product review explains the problem or need (and existing solutions or workarounds), introduces the product, and describes how the product fits in the industry (who the competitors are and what the vendor hopes to accomplish).

The main body of the article explains how the product works and how well it performs. You should address some or all of the following in this section of the product review:

• Method of operation: Is the product menu driven or command driven? Is the interface graphical?
• Integration: Can you integrate the product with other products from the same vendor? With tools of other vendors that automate other parts of the process?
• Extensibility: Can the product's underlying structure be used to add new functions or facilities? Can a vendor's "dictionary" facility be extended to let you store and use new types of application information?
• Customization: Can you customize the product for each system, library, or user? Is source code available?
• Performance: Does the product perform as advertised? Does it perform well? What is its impact on system resources such as CPU, memory, or disk? How does it measure up to established benchmarks?
• Ease of use: How easy is it to install? Are there shortcuts for advanced users? How much learning time is required to perform useful work? Is the user interface consistent with other products from the same vendor? Does the interface comply with established standards?
• Error handling: Are the messages descriptive? Can the program recover from user errors? Is the product solid or buggy?
• Documentation: Is online help available? Is it context sensitive? Is help available at the menu, screen, and field levels? Is there a manual? Does it include a table of contents, examples, illustrations, screen/report samples, index and glossary, reference cards, or templates?
• Value for targeted customer: How does the price compare to similar products? Is the price in line with the functionality? Does the vendor provide telephone support? A warranty?

The conclusion (along with some figures) is the only part of the review some readers look at. Keep this is mind. Be objective; don't be unjustly harsh or critical of a product, and don't give gushy praise to one that is good but can be improved. The conclusion should answer questions like: Is the product worthwhile? Does it solve the problem or fill the need described in the introduction? Does it perform as advertised? Is it reasonably priced? Should readers buy it?

Figures for a product review generally include a product information box and a features table. The product information box includes vendor contact information, price, and a summary of the product's pros and cons. The features table lists the important features of the relevant product category and indicates the extent to which the product under review demonstrates those features.

In addition, comparative reviews include a capsule summary, which shows, in a nutshell, the overall review of the products and how they stack up against each other. Categories such as reliability, performance, documentation, ease of use, and overall value are assigned ratings such as:

• Excellent (Tops in its class. Meets all essential criteria and offers significant advantages)
• Very good (Meets essential criteria and includes some special features)
• Satisfactory (Meets essential criteria)
• Poor (Falls short in essential areas)
• Unacceptable (Fails to meet minimum standards)

Once a review is turned in to iSeries NEWS, we edit it for accuracy, clarity, and our style conventions. As part of this process, we provide the vendor with a copy of the article for the sole purpose of ensuring technical accuracy. (If the article compares products from multiple vendors, each vendor is sent only the portion of the text that applies to that company's product.) Vendors wishing to make technical corrections are asked to discuss them with the author. If you and the vendor cannot agree, the vendor may be offered the option of providing a short (250 words) "vendor response box."

Demo Booths provide practical, technical looks at application development and system management/operation tools. In Demo Booth, software vendors explain working examples that use their products to solve common 3X/400 problems. The vendors speak for themselves -- iSeries NEWS technical editors referee submissions to eliminate promotional material, but vendors select their own problems, solutions, and styles of presentation. Demo Booth examples provide a brief introduction to tools that may help readers in their own environments. 1,000-1,200 words.