Writing Technical Articles for CODE

Technical Article Objectives

The objectives for CODE Magazine's technical articles ("How-To Articles") is to teach the reader how to use a certain technology, product, or technique. The author first sets the stage by introducing the scenario to make sure the reader understands what the article is all about and what the pre-conditions are. The author then methodically walks the reader through using the technology, technique, or product. The article focuses on how to do certain things. Articles do not focus on things that do not work. It may at times be beneficial to warn the reader of certain pitfalls and explain how to avoid them, but overall, CODE articles take a positive approach and focus on how to make things happen.

Article Format

Technical articles start with a brief intro paragraph. This is the paragraph people read and decide whether they want to read on. The introduction is also often used as an article abstract in eBooks and the like. Consider the intro to be an advertisement for the article. If the reader's interest can't be captured by the intro paragraph, the reader is not likely to read the entire article.

The article then progresses to methodically explore the topic at hand through explanations, code snippets (and listings), and screen shots (or other illustrative graphics). Make sure you explain topics thoroughly. CODE Magazine's philosophy is to take the space needed to explain technical aspects in detail. We want the reader to not just be aware of a certain technology or technique, but we also want the reader to be able to then apply whatever they learned without the need for further explanation or books or web sites.

Include Images and Screen Shots

Include screen shots and other images from your application. Screen shots should always be taken using standard color schemes (especially if you include screen shots showing source code, make sure you reset Visual Studio (or whatever IDE you are using) to the default colors. Send your screen shots as BMPs without compression. Never resize or compress images.

Photographs always need to be sent in high resolution (300dpi min). Photos of the development team or your offices are often interesting.

Note: In general, code examples should not be included as screen shots. Use code snippets or code listings instead (see below).

Code Snippets and Code Listings

Technical articles often require source code examples for illustration. Depending on the length of the example, we consider it either a "snippet" (10 lines or less) or a "listing" (more than 10 lines). Snippets are laid out in place within the flow of the article. Listings are positioned separately and referred to from the main text by listing number.

When creating code listings and snippets, copy the source code from your IDE using standard syntax coloring schemes. Make sure syntax coloring remains intact when pasting source code into articles. If you are using an IDE that doesn't create standard colored code you can paste, or have trouble with the coloring for another reason, check out our Code Snippet Tool, which can handle small snippets with appropriate coloring applied for most types of code. (However, it can't do everything, so if you have something beyond the capabilities of this tool, it is up to the author to provide appropriately colored content).

Make sure to use the latest CODE Magazine template and follow the code guidelines (especially number of characters per line) as defined in the template.

Length of Article

CODE Magazine articles do not have a specific length requirement or limit. It is our philosophy to take as much space for an article as is warranted by the topic to provide a good in-depth explanation to the reader, without wasting space or time. Typical CODE Magazine articles can be anywhere between 3 pages and a dozen pages. However, if your article topic is approved for writing, please coordinate with the editor to provide a rough estimate to enable us to plan space requirements.