---

Writing for ONJava/java.net - Process Guide

by (in reverse order of revision) Chris Adamson, Jon Mountjoy, chromatic, and Edd Dumbill
14 Apr 05

The commissioning process

ONJava and java.net have a simple commissioning process. If you have an idea for an article, send an abstract or outline to . Your proposal should be 1-2 paragraphs (or 5-10 bullet points) and should express what the article is about, why it matters, and what material you intend to cover (this should, as a side-effect, prove that you're addressing points one and two). I will respond within a few days to indicate whether or not this is a topic that has not recently been covered on the site and is of interest to our readership. Please include links to examples of your previous work if you have any. We usually send a contract after you've submitted a first draft that meets our standards (it doesn't have to be ready to publish, but it has to be at a level where we know it will eventually get there, perhaps with some rewriting). The writing process is described in detail below.

To make things easier for invoicing, each article needs a separate contract. The single exception is if the contract discusses a series of articles or a column. In that case, the contract will specify the number and frequency of articles.

If I've worked with you before, I may pitch you article ideas on subjects I think you could discuss well. For this reason, it's always a good idea to tell me about your strengths and your interests. In this way we can build a relationship for future articles.

Initially, it's better to propose just one article. Writing is sufficiently different from developing and adminstering, and we've found that it's easier to ease into it gradually.

Because we work primarily with freelance writers to cover many topics and subjects, we generally limit an author's paid contribution to one per month. This helps us spread the fortune, fame, and fatigue around nicely.

Writing your article

Write your article in HTML, using the onjava-javanet-template.html file as a guide to our very simple HTML style. Do not submit Microsoft Word documents. These will be discarded without being read.

Write in a compact, friendly, way. Probably the biggest mistake I see is authors writing for themselves or for some mythical audience of "experts", not for the novice developer who just wants to learn more about a new topic that interests them. There are a lot more of the former than the latter out there. Also, the style of our articles is best described as "feature article", not "academic paper" ? hint: if you start with a formal abstract, you're not writing a feature article. Articles should generally be around 2,000 words, which does not include the code. If your article is technical, which is usually the case, include example code. Don't feel pressure to keep your example code very small; it's better to be complete and correct than to try to squeak in under the word limit. Don't count code in the word-count.

The first few sentences of your article are critical in getting the attention of the reader: don't ramble, and use these sentences to explain in clear and interesting terms what your article is about, and why it matters.

Include plenty of hyperlinks to related articles and specifications. Perform searches on ONJava to determine which articles are related to your own. Hyperlink throughout the body of your article and try and include a "resources" list at the bottom of the article with links to this related material. It's a good idea to hyperlink the first use of any technology or specification to its home too. You might also want to link programming, mathematical, and other concepts to their entries in the Wikipedia. And if you have a sample code file (usually a zip or tar.gz), have a link for it in this section too.

First Time Writers

If you don't yet have much experience writing an article for publication, I will work with you on your outline and drafts. It's normal for an article to end up much different from the original plan. My job is to help you pick the right subject, tone, and approach to create an interesting and informative piece of work. I also want to find a good balance of things to publish.

It's very important to achieve a good narrative flow. It's much easier to write from a well-organized outline than it is to rework a poorly organized article.

Reviewing

Please check your work before sending it on to us. Don't check your article straight after writing. Get a good night's sleep and come back to it fresh.

Asking trusted colleagues, friends, or community members to review your article will make everyone's life easier. While we can correct inevitable typos after the fact, and we know things change, it's often good to have another set of eyes looking over an article before handing it in. This also has the nice benefit of getting a ready-made set of fans to promote your work when it goes live.

The Editing Process

Once you've submitted a first draft, I'll read over it and make comments on the organization, writing, style, tone, etc, and perform small copyedits where obviously appropriate (the main copy-edit comes at the end of the process). My comments will take the form

which, as an XHTML comment, won't appear in the browser. This may indicate a change I've made, a change I'd like you to make, a question where I simply don't understand something (which means there's a good risk readers won't understand it either, etc.). This is a to-do for the next draft and if you want to add a comment of your own to explain something, ask a question, etc., then just do so in the same format with your own initials ("ca" are my initials, so that's what you'll replace). We'll go back and forth, rewriting and editing, until I think the article is ready to be published.

Before your article goes live, I will send you a link where you can preview how it will actually look. There may be minor formatting and copyediting changes between the preview and the actual publishing, but there will be no content changes unless you request them. I do want you to have the chance to make any final adjustments.

Getting paid

In order to get paid, we need two things from you: the contract, which you should have signed and returned when it was sent you by an editor. Secondly, we need an invoice.

After you get the preview URL, you'll also be e-mailed an invoice template which you should complete and return to us. If you live in the contintental U.S., payment should arrive within 30 days of invoice approval. Add two weeks if you live outside of the US. Sometimes it's a day or two shorter or a day or two longer. If it's more than a week late, please let me know and I'll look into things.

After your article is published

We'd like your article to get the widest possible readership, and you can help. If your article is of interest to some other community than might normally read ONJava, you may like to draw it to their attention, or suggest to us ways to promote your article. Prime candidates for sites that may be interested in linking to your article are sites that you have listed in your resources section.

The contract specifies that you maintain the copyright to your work. We ask that you do not republish it on the internet within 30 days and we also ask that if you do republish it that you include a link to the original URL.

Additional details

If you haven't written for us before, please submit a short biography (5-10 lines) along with your article. This will go on your author page. You're also welcome to suggest updates to your author page as appropriate. If you have a headshot, please also send us a tiff or a JPEG that can be used.

Questions

If you have any questions, please e-mail me: