Introduction
Writing a Proposal
Types of Content

Feature Articles
Reviews & Profiles
Interview
Soapbox
Postmortem
Cover Art

Writing Guidelines

Word Processor Format
Graphics and Illustrations
Formatting Code
Commenting Code
URLs and References
Spelling & Grammar
Writing Xojo and Other Names
Abreviations and Acronyms
Versions of Xojo

Writing Your Article

Structure
Style
Audience
Article Length

Sending Us Your Article
Payment
Copyright Information
Communicating With Us
Copyright Agreement

Purpose of Agreement
Agreement

Introduction

This guide will explain to you the procedures and requirements for writing for xDev Magazine. It is advised you read this document thoroughly before beginning your writing project. Following the guidelines within will not only increase the chances of us publishing your work and the amount we pay, but it will save us time in editing and production.

Writing a Proposal

If we're interested, we'll let you know. Simply expressing an interest doesn't guarantee that we'll use your article, however. But you'll have a greater chance of us publishing it than if you simply submit a finished article unsolicited.

Types of Content

Feature Articles

The majority of our articles are of the "How To" nature. They should be focused and demonstrate a particular technique or concept and include plenty of sample code. Real world examples are most valuable. For instance, an article explaining how Sockets in Xojo work is not nearly as interesting as an article showing how to write an actual application.

General programming techniques and algorithm design are also hot topics. For instance, an article on how to add "undo" support to your application, or a feature comparing various search methods.

Articles about the business side of software writing are also needed. For example, how to distribute shareware, obtain publicity, copyright issues, collecting payments, serial number schemes, etc.

Features are 1,500-6,000 words and should include extensive screenshots and graphics and some source code. Extended amounts of source code and other resources may be placed on the xDev Magazine website for readers to download.

Reviews & Profiles

Reviews are brief articles summarizing the good and bad points of a tool of interest to Xojo programmers. Tools are anything that helps the Xojo developer. They can be Xojo plug-ins, classes or modules, programming books (they don't have to be Xojo-specific), or even a graphics program, such as an icon editor. They can be commercial, shareware, or freeware. Reviews of tools are rated on a 1-5 scale calculated via the following formula:

• 20% - Appearance/Interface (Does it look professional? Does it follow Apple's UI guidelines?)
• 20% - Usability (Does it do what it promises? Is it useful?)
• 20% - Stability (Does it crash?)
• 20% - Value (Is the pricing attractive or prohibitive?)
• 20% - Innovation (It is a unique or innovative product?)

Profiles are unrated reviews of software developed with Xojo. These are designed to promote and demonstrate the high quality and variety of software being developed with Xojo. We are especially interested in unique and innovative solutions. These reviews are not rated, but the review may be critical if the product is not of high quality.

Reviews and Profiles have a maximum length of 500 words plus one graphic (screenshot, product photo, or company logo); must include the manufacturer's contact information (website, email, etc.); the price of the product; and any unusual system requirements (for instance, doesn't work under Mac OS X).

Interview

Soapbox

Postmortem

For instance, if you wrote a popular shareware program, you could write about your troubles and trials and successes in creating the program. This wouldn't necessarily mean you have to release the source code of your project, but some code snippets would be helpful in explaining what you learned during the process.

Your project does not necessarily have to have been a success. You could explain, for example, how you tried to rewrite a C++ program in Xojo but failed, because of limitations within Xojo. (Obviously, the tone of the article should be positive, even if the experience was not.) The point is to emphasize what you learned through the process, and what you'd do differently if you were to do a similar project again.

Postmortems are 1,500-3,000 words and should include extensive screenshots and graphics and perhaps some source code. All postmortems are assigned by an xDev Magazine editor, so you should first write a proposal before submitting an article. Postmortems should also include a "Developer's Toolbox" table like this (from RBD 1.3):

Cover Art

We don't use much artwork inside the publication (other than photos, screenshots, and diagrams), but if you have an illustration you'd like us to use (perhaps as part of an article you've written), we may consider it.

Our artwork needs are fairly specific, so it's best to contact us regarding your idea before you spend a lot of time creating it. We may have revisions to your concept.

Writing Guidelines

Word Processor Format

Markdown is a very simple plain-text format that doesn't use tags. This makes it much easier to write and read. We convert the Markdown to XML prior to publication, so using our Markdown standards gives us a consistent file format. tagging is similar to HTML tagging, but far more powerful. By using the tags we specify, we can easily format your article for publication as well as repurpose it for the web and other uses. Note that different types of articles will require different sets of tags.

For example, a typical article might be tagged like this:

To make it easier for you tag your articles, we've written a detailed explanation on how to do it: you may download the PDF manual here.

We've also created a program, xDev Author, which will let you quickly write articles in our format. You may download the program here. The instructions for using xDev Author are within the xDev Markup Guide.

Graphics and Illustrations

Bitmap graphics like photos or screenshots should be saved in Photoshop (PSD), JPEG, or PNG formats. Specify high-quality (minimal compression) when using lossy formats like JPEG. Photos should have a resolution of at least 200 dpi at 100% size. For screen captures, capture only the information necessary to convey your point. If possible, use a screen capture utility that lets you grab just the active object you need (window, menu, etc.).

Do not include figure numbers or labels within your illustration or screenshot. Instead, write a separate caption and label it "Figure X" where X is the number of the figure. Figures should be numbered consecutively from the beginning of your article. Don't assume that a figure will appear adjacent to the text that refers to it: always refer to a graphic by number (i.e. write "See Figure 4." not "See graphic below." or "See graphic at left.").

If you have ideas for graphics you'd like to include but aren't an artist, please do a rough sketch and include a written description and we'll see about having the drawing created.

Formatting Code

• Use spaces between all symbols and punctuation (except for parenthesis), so i+1 becomes i + 1.
• Put comments on their own line (inline comments add to line length).
• Break up your code with blank lines to group related sections together and make it more readable.
• Use consistent capitalization of variable names and reserved words. Our preferred approach is to use all lowercase for reserved words and to capitalize only the first letter of words inside variable names. So theList is correct and TheList is incorrect (but this isn't a big deal so don't sweat it if you use a different style).
• Use a consistent scheme for naming variables. It'd be too difficult for us to force you to name variables our way, but as long as you're consistent, it shouldn't be confusing for readers. Our preferred approach is the following: use a lowercase c or k for beginning constants, a lowercase g for globals, and appending Class to the end of Classes. So kMaxScore would be valid for a constant, gPlayerScore for a global, and gridCellClass would be good for a class type.
• You may use either tabs or spaces to indent code, but be consistent! (Don't do some code with spaces and some with tabs.) This is very important to preserving the structure of your code. Copying or exporting code from the Xojo IDE will usually work fine.
• Try to keep lines at less than 100 characters, as longer lines will wrap in listings, making them more difficult to follow.
• All comments should use the dual-slash form (//) not the apostrophe (').

Here's an example of a well formatted code snippet:

Function returnColumnWidth(colNum as integer) As integer
    dim i, n as integer
    
    // This function adds up the widths of columns up
    // to colNum and returns it. It is used to calculate
    // the starting position of column colNum.
    
    n = 0
    for i = 0 to colNum
        n = n + val(nthField(theList.columnWidths, ",", i + 1))
    next // i
    
    return n
End Function

If you aren't including the entire routine in your snippet, begin or finish it with three dots to signal that more code precedes or follows. For example:

    ...
    // Be certain column width is at least the minimum size
    
    n = returnColumnMinimum(theColumn)
    if cWidths(theColumn) < n then
        cWidths(theColumn) = n
    end if
    ...

Note that xDev publishes source code in two methods: within the body of the text (embedded code), and in a separate code listing. Code within the text must be pertinent to the subject at hand and generally consists of shorter snippets. It is ideal for a tutorial as the structure is text, code, text, code, etc. However, if you're include a very long routine, you should run it as a Code Listing at the end of your article and refer to it by number within your article.

Here's a sample of embedded code as it appears in the magazine (the body text is just dummy copy used for a mockup):

Code listings are longer portions of code labeled by number and referenced in your text (i.e. "See Code Listing #1"). Please number them beginning with #1 as they appear in your article.

Here's a sample of a separate (non-embedded) Code Listing as it appears in the magazine (the line on the right represents the maximum non-wrapping width):

Commenting Code

    // First we make sure the folderitem isn't bad
    if theFile <> nil then
    ...

Use the text of your article for explaining your algorithm and general methodology. Comments shouldn't duplicate your article -- they are there to remind the reader what's happening in that section. If your article has suggestions for improving the code or alternate algorithms, don't include comments to that effect in your code -- keep the code as complete and professional as possible.

URLs and References

For URLs, do not include HTML markup ("href") to hot-link some text. Instead, simply include the full URL enclosed within parenthesis to prevent additional text or punctuation from being included into the URL: "Please visit my website (www.stonetablesoftware.com) for more information on this."

Note that you may need to rewrite your sentence for this to flow correctly. For example, it's very common for writers to refer to a website at the end of a sentence, like this: "For more information, go to wikipedia.org." The problem with this is that it includes a trailing period which can inadvertently be included in the URL when hot-linked or copied.

A better method is to rewrite the sentence to "Go to Wikipedia (wikipedia.org) for more information." The parenthesis helps prevent the trailing punctation from being included with the URL.

If you are referring to material on your own website, please note that if this is something the user will need to understand or use your article, then we require that it be made available via the xDev website. You're free to mirror it on your own site, of course (you can include a URL to your site in the Reference section at the end of the article), and you keep the copyright on any copyrighted material, but xDev should have distribution rights. As a general policy we want our readers to know that if something is required for an article it is freely available on the xDev website.

If the item isn't required for the article but merely referenced, you may simply include the URL within your article. However, if the item is a product that you sell, you need to mention that within your text. For example, "...a similar product is this author's own rkRocketClass, which sells for $10 with a free 30-day trial." We don't want to give readers the impression that authors are simply pumping their own products for sale. (It's fine to refer to your own products, just make sure it's clear if it's a free product or if it's a sale product.)

Here's a sample bibliography entry:

Jenson, William and Mary Foil (editors). "Compression Algorithms Revisted," HighTech Weekly, No. 86 (July 4, 1999), pp. 73-94. DVU Press.

Spelling & Grammar

Abbreviations and Acronyms

This is an article about writing your own File Transfer Protocol (FTP) server in Xojo. This was originally printed on the xDev University (XDU) website. The original XDU article did not cover Mac OS X, but we've updated our Xojo code to support Cocoa compiling.

Creating your own FTP server isn't difficult, but you must read the many RFC (Request For Comment) docs that explain the FTP standard....

Versions of Xojo

* If your code is such that it greatly depends on features of a pre-release version of Xojo, we might make an exception, if we feel the features are at the core of your article. But you must make it very clear that your program requires a pre-release version, specify which version it requires, and explain why you had to use that version. Because of the lead time required for publication, it may be that the pre-release version used is officially released by the time that issue of the magazine is published, but there's no guarantee that Xojo, Inc. hasn't changed something from the pre-release version that renders your project incompatible.

Writing Your Article

Structure

This article will explain how to launch the Xojo application.

First, you find your Xojo folder. Then you double-click the Xojo icon. You're done!

Now you know how to launch Xojo on your own.

Obviously you want to expand on this a bit (and pick a more challenging subject ;-), but this is the basic idea behind any article. Your introduction could include a story or some background on how you came up with the idea or need for whatever it is you are going to explain, followed by the actual implementation of a solution. Your conclusion wraps things up and perhaps indicates future directions the reader could take to make the program better, or do further research on the subject.

Style

Audience

Article Length

Certain types of articles have specific length requirements: columns, for instance, should be consistently about the same length. Reviews must fit into a pre-defined amount of space and must all be about the same length (about 500 words).

Also, keep in mind that the length of an article includes source code published as part of your article. For large projects, we can't print the entire source, but we definitely want excerpts. Depending on your audience, you may omit "obvious" portions of the code and allow the reader to download the complete project from the xDev website. For some features, half the article can be source code, so keep that in mind if you're intimidated at having to write a 3,000 word article! (Just be sure you explain any source code you use in the text.)

Finally, for most articles we pay by the word, but that's words we actually publish. If you submit a 5,000 word article and we trim it to 3,127, you get paid for 3,127 words.

Sending Us Your Article

Be sure to include all necessary resources for your project, and include plenty of folders to organize everything appropriately. For example, include an "article illustrations" folder for all screen captures and graphics, an "ABC project folder" for your source code, etc. If we get everything all lumped together in one folder, we may have to return it to you as we may not be able to make sense of all the parts!

At the end of this document is a copyright release and an author information form. Be sure you complete these and fax or email them with your submission. If you are a U.S. citizen, your social security number is vital, as otherwise we cannot pay you.

Payment

Payment amounts vary according to article type, length, significance, quality, and the amount of editing/rewriting required. Below are our current rates. As our subscriber base increases, these amounts will be adjusted accordingly.

• Soapbox: n/a
• Review: $25
• Regular Column: $50
• Feature Article: $0.03 per word (typically $60-$150)
• Postmortem: $0.03 per word (typically $50-$100)
• Cover Art: $50-$75

If you'd prefer to receive credit towards an xDev Magazine subscription, we can do that instead of sending you a check. We can also apply credit towards an advertisement in the magazine or on the xDev Magazine website. If you plan to write for xDev Magazine frequently, we can also save your payments on account until the total reaches a more substantial amount. (This might be appropriate for writers from foreign countries where the fees to translate currencies can be excessive.)

Copyright Information

In submitting an article, you are granting xDev Magazine magazine the worldwide right to publish and re-publish your article in any medium, in any language, in whole or in part. In the event that copyright is retained by the author (or author's employer), the publishing rights are granted to xDev Magazine. This allows for copyrighted code to be submitted in an article without its use being restricted for xDev Magazine or the author.

For authors this means that your work, when published, becomes property of xDev Magazine. This is what we pay you for when your article is published.

All articles must be original works and may not appear in any other publication without prior consent of xDev Magazine for a period of one year from publication by xDev Magazine. This restriction includes distribution in any form, such as bulletin boards or on-line services. If you want to escape the restriction, you can do so by making substantive changes first; that way, what you now publish is not the same article we published. If you wish to have the article itself reprinted elsewhere, you must first receive written (or email) permission from xDev Magazine. We grant you the right to use the article text, pictures or related source code either personally or commercially without restriction, though; and during the restriction period, we will in fact usually grant authors the right to republish their work, but you have to get our permisssion first. If we grant permission we will request that the author state that the article was originally published in xDev Magazine. For example, "This article was originally published in xDev Magazine 1:2 (Oct./Nov. 2002)." For precise wording on this copyright information, see the Copyright Agreement at the end of this document. Again, all information in that agreement supersedes the text here. After the limitation period of one year is up, you can of course reprint the article without limitation. Note that if all you want to do is distribute copies, we'll be happy to provide a reprint master of an article.

xDev Magazine also grants to those who receive the magazine or other materials, in either printed or electronic form, the right to use parts of the source code in their own project, be it personal or commercial, provided they duly credit the the appropriate issue of xDev Magazine. For example:

XYZ Program by R. B. Programmer.
Portions Copyrighted by xDev Magazine as seen in the Sept./Oct. 2012 issue.

Communicating With Us

xDev Magazine
P.O. Box 872
Lafayette, OR 97127

General email Addresses:

Editorial:
Article Submissions:
Press Releases:
Tips:
Letters to the Editor:
"Ask the Expert" Questions:
Circulation, Customer Service, Accounting:
Ad Sales:

If you prefer, a high quality PDF version of this contract is available here (89K).

Copyright Agreement

Purpose of Agreement

Agreement

Author desires xDev Magazine to publish the Article in a future edition of xDev Magazine, and hereby submits the Article for pre-publication review via electronic mail.

xDev Magazine will review the Article at its convenience, and shall notify Author of its acceptance or rejection. Such notification shall be in writing or by telephone or fax or electronic mail, but in no event shall such notification occur later than 90 days after submission. If xDev Magazine fails to notify Author within the 90 day period, Author may seek publication elsewhere and may withdraw the Article from consideration upon 30 days notice in writing, email, or by fax to xDev Magazine.

Author shall make any and all revisions and modifications to the Article requested by xDev Magazine. Further, xDev Magazine reserves the right to make whatever editorial changes it sees fit, in its sole and absolute discretion. Author shall also submit machine-readable copies of any relevant computer code or software, and copies of any and all resource material necessary for xDev Magazine to verify the technical or factual aspects of the Article at the time of article submission.

Once the Article is accepted for publication, xDev Magazine shall publish the Article in xDev Magazine magazine within 365 days of such acceptance. If xDev Magazine fails to publish within this period, Author may withdraw the Article upon 30 days written notice to xDev Magazine. Upon such withdrawal, xDev Magazine shall have no further obligation to Author of any kind, and shall have no rights of any kind in the Article.

From the time of acceptance for publication, unless timely withdrawn by Author, Author hereby irrevocably assigns and conveys to xDev Magazine all rights to publication, display, transmission, and any and all other exploitation of the Article in all media, in any language, worldwide. These rights shall be exclusive to xDev Magazine from acceptance through one year from the date of publication. The date of publication is the first day of the month on the cover of the magazine the Article first appears in. These rights shall include rights to publish reprints or to include the Article in any future collections of xDev Magazine material including, but not limited to, an annual xDev Magazine CD-ROM. These rights shall also include the right to authorize republication of the Article in other media and periodicals, and the right to use the Article for all commercial and merchandising purposes that pertain to xDev Magazine magazine or to DesignWrite. DesignWrite shall have no rights of any kind to any computer code or software contained in the Article, whether used as example, or otherwise, but may make such use of such code, concepts or software as any reader of the magazine would be expected to do. Author is entitled to use the article text, pictures or related source code either personally or commercially without restriction. Furthermore, if indicated at the time of article submission, Author may retain the copyright of said computer code.

After one year from the date of publication, all of the rights mentioned in paragraph 5 above shall continue but shall be non-exclusive to the extent that Author may utilize and display the Article for any non-profit purpose, and for any other purpose in which the primary source of revenue is not sales of copies of the Article. Author may not utilize, display, reprint or republish the article for profit without prior written permission. For example, Author may distribute copies of the Article without charge to attendees of a symposium or conference in which Author is paid a fee to speak, but Author may not sell copies of the Article, whether Author speaks or not. Whenever the article is reprinted or republished by the author, such reprint or republication shall state that the article is reprinted from xDev Magazine Magazine specifying xDev Magazine's date of publication. Author may substantially rework an article for publication elsewhere without any restrictions by DesignWrite.

xDev Magazine shall pay author its usual fee for articles of the same, quality, length and type. Such payment shall be due 30 days after the first day of the month of publication. xDev Magazine's usual fees are described in the version of its "Writer's Kit" that is current at the time of submission. Judgment as to the quality, and type of article shall be in the sole and absolute discretion of xDev Magazine. Author warrants that the Article is entirely Author's original work, (except quoted items which must be correctly attributed) and has not been previously published. Author also warrants that the Article and its publication violate no laws and no rights of any individual, group, association, corporation, governmental agency, or other entity.

Both Author and xDev Magazine acknowledge that the Article was written at the Author's own direction and not at xDev Magazine's direction and that the Author's only relationship to xDev Magazine is that of an independent contractor.

This agreement shall be governed by the laws of the State of California. Any provision found to invalid or unenforceable by operation of law or public policy or for any other reason by any court shall be severed and the remaining provisions shall be treated and construed so as to most nearly achieve the purposes set forth above.

Any and all notices required under this agreement shall be deemed made three working days after placement in regular US mail, or one working day after fax or email transmission. Addresses for all such notices for Author appear below and for xDev Magazine below.

By causing a facsimile or electronic mail copy of the Article to be received by DesignWrite (submission), author accepts and agrees to the terms and conditions of this contract. The act of submission shall be all that is required to evidence author's acceptance of all of the terms and conditions of this agreement. Lack of signature execution by author shall have no legal significance whatever. Any changes or alterations made by Author in copy derived from this Agreement shall be null and void and the submitted Agreement shall be interpreted and enforced as if such changes had not been made.

DesignWrite accepts and agrees to the terms and conditions of this contract at any time it accepts delivery of a submitted Article. The lack of a signature execution by DesignWrite shall have no legal significance whatever, providing that no modifications have been made by Author to this Agreement.

Understood, agreed, and accepted this _____________ day of ____________________, 20_____:

Author: _______________________________________  _______________________________________
                 (Signature)                                     (Print name)

Street Address: ________________________________________________________________________

City: __________________________________________________________________________________

State/Zip: ______________________ Country: _____________________________________________

Social Security #: _____________________________________________________________________

Phone: ___________________________________________ Fax: ________________________________

Email: _________________________________________________________________________________

xDev Magazine
PO Box 872
Lafayette, OR 97127
email: