Originally posted by Chris Adamson

Copied here for quick reference by Satya Komatineni


Quick Reference

0. Index.html

1. Topics of Interest

2. Process Guide

3. Style Guide

4. Get Template Source

5. View Template

Writing for ONJava/java.net - Style Guide

by Chris Adamson
v 0.5, 13 Mar 06

This guide is meant to help you write an article that fits the general style and approach that we look for ONJava. After editing for a while, I have seen a lot of the same problems and hope reading this document can help you avoid them, resulting in a better article that gets published sooner and more easily. There is a companion document, onjava-javanet-template.html that addresses HTML source-level formatting details (please be aware that we only accept articles in HTML -- Microsoft Word documents will be discarded without being read). Another document, onjava-javanet-processGuide.html covers the process of proposing, submitting, and being paid for an article.

If you take away only one thing from this guide, it's this: write to be read. In other words, always be aware of what the reader is getting out of your article, craft the article in ways to help the reader understand the material, and don't create any roadblocks that will prevent readers from enjoying the article and learning from it. As an editor, my philosophy is that what counts is what readers get out of an article, not what the author, editor, producer, etc. put into it.

Parts of an article

An ONJava article consists of four sections:

  1. Introduction - this establishes the point of your article (what you're covering, why it matters), and what you intend to cover along the way. This should be at least one paragraph, and could be significantly larger if there's a lot of new ideas to introduce before you can get started
  2. Internals - this is the main part of your article (perhaps 90% or more of its word count), in which you cover new API's and programming techniques, describe a test methodology and results, etc. This material should have a narrative "flow", so the reader understands why one part leads to the next. You may find it helpful to periodically state or restate why you're covering certain topics, in terms of the material you set out to cover in the first place.
  3. Conclusion - this section recaps what you've covered, and what the reader should take away from the article. It is also very helpful to provide some idea of what interested readers can do next - what else could be done with these ideas, where can they go for more information, etc.?
  4. Resources - this is a
      list that should be at the end of every ONJava article, collecting links relevant to the material covered in the article, like the home pages for any projects or products you've mentioned, or articles or books for further reading. If you are providing a sample code zip or tar.gz file (most articles should), the link for it should be the first item in the list. The resources header should look like this:
        

      Resources

      You can then refer to the resources section in the body of the article with a link like this:
        See the resources section for the sample code.

Length

Our ideal article size is 2,000 words. Research shows readers bail out of longer articles, so keep things short and focused. A 4,000-word article will be returned to you with suggestions for cutting half of it out, and a 7,000-word article will probably be returned to you unread.

Approach

As I said in the introduction, write to be read.

One way to do that is to appeal to the reader's self-interest: think of what they're going to get out of reading this article. Maybe they'll be able to build web pages more easily, create more reliable code, get better performance, etc. Whatever the benefits of reading the article, it's helpful for you as an author to know what they are, so that when you re-read your work, you can say "is the reader going to get the benefit of reading this article?"

Despite Java's balkanization, you might be surprised to know that many readers will read articles well outside their realm of experience ? for example, few developers actually code J2ME every day, but many want to understand it better. For this reason, you should try to make your article accessible even to those readers who aren't subject matter experts in what you're covering. Often times, you can catch people up with just a phrase here or there, providing a little information to allow the reader to infer enough information to keep reading your article.

For example, most readers of this document haven't worked with QuickTime (which I wrote a book about), and will not understand the following description of how it handles MP3 metadata:

The tags become children of the moov atom's udta, which is created if necessary.
but if I just add a little bit to catch you up:
The moov atom, which describes the movie's structure, gets a new or updated user data (udta) atom, with the tags as its children.
Even if you'll never write a line of QuickTime in your life, you can probably keep reading and get the general idea of what I'm talking about, since this explains what moov is, what udta is, and what their relationship is. And it's still only one sentence.

The "reader expectations" paragraph

Because it's possible to help readers along even if they aren't familiar with your topic area, I frown somewhat on the "reader expectations" paragraph, the kind that goes something like:

The reader should be well-versed in Struts, Spring, Hibernate, WebWork, SiteMesh, JSP, and JSF ? preferably a committer on at least one of these ? and should be familiar with the changes checked into to the MongoWebApp project last week on the experimental branch.
That, frankly, is a good way to narrow your target audience down to one reader: yourself. There are times when setting prerequisites is appropriate, but give your readers a little credit and don't send them away if you can help it.

Multi-part articles

Important update (Dec. 2005): We are no longer accepting series of more than two parts, and then only from established writers. We strongly encourage you to re-think your material so it fits into individual, independent 2,000-word articles. Analysis shows that readers do not stick with long series, and do not go back to earlier articles to read prerequisite material.

If you're writing a two-part article, you need to make sure that each part "stands alone", and is an interesting article in its own right. It's not very interesting for the reader to read a "part 1" that's just set up for a second part that hasn't been published yet. In a case like this, try to see what value part 1 has, and try to develop that. For example, if you are developing a complex GUI component in your article, with part 1 about the model and part 2 about the visual representation, you could close part 1 with some unit tests to show that the model behaves correctly.

Writing: Grammar

Writing to be read means, obviously, following the rules of English. The more clearly you express yourself, the better received your article will be.

Probably the best advice I can give in this area is to read (or re-read, if it's buried in your school books) The Elements of Style by William Strunk, Jr. and E.B. White. The 1918 first edition is available online, and a more modern fourth edition is worth the purchase price several times over.

Some of the most important grammar principles to remember include:

If you are unsure of your writing, particularly if English is not your native language, the best thing you can do is have someone else read it first and give you feedback.

Writing: Common style points

We prefer to let a writer maintain his or her natural style as much as possible. I mention the following points only because they come up frequently.

Writing: HTML for Special Elements

A few basic rules suffice for special content like code and images. These are described in an Authors' Guidelines document that is common to all O'Reilly Network sites. Among the most important considerations:

Code: Sample code .zip or .tar.gz file

Your sample code file should be the first link in the resources section. It should contain only your source and not third-party libraries that your code would need in production (we don't want to be responsible for the license terms of n libraries times m articles published on the site). Use the article to describe any dependencies your code has, link to those sites, and trust the readers to get and install the code themselves if they really want to try it out -- typically, they're just interested in your source.

Finally...

Ask us for help. That's what we're here for: making your article as good as it can be.