Writing for ONJava/java.net

android Android

web Web

3-Aug-06 (Created: 3-Aug-06) | More in 'CS-Java'

Writing for ONJava/java.net - Style Guide

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:

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
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.
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.?
Resources - this is a

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:

Use the active voice - The passive voice sounds affected, curious, and simply weak. Compare:
One or more Components may be contained by a Container
to
A Container can contain one or more Components.
The second version is more direct, and keeps the Container as the subject of the sentence. By the way, this is Strunk & White's 11th principle.
New thoughts get new paragraphs - If you're starting a significantly new thought, end the paragraph and start a new one. Keep related ideas together in paragraphs: say something, develop it, and when you need to move onto another point, start a new paragaph. This is Strunk & White's 9th principle. Also, do not insert a in mid-paragraph when you have a sentence that you're not sure deserves a new paragraph. Make a choice one way or the other.
It's means "it is". Its means "belonging to it" - Yep, it's in S&W too, principle #1 in fact.
Let's, not Lets - I don't think lets even exists in English, except maybe for an edge case of tennis terminology.
Understand the colon - The colon can be used to set off lists, amplify/clarify a point, or set up a quotation:
Java has three major varieties: J2ME, J2SE, and J2EE.
Java applets do what DHTML cannot: bring a full suite of client-side functionality to the browser.
With your JAR built, you can send it to all your friends: "Write once, run anywhere."
Understand the dash - The em-dash sets off material with a long break or interruption.
The key to deploying a WAR file ? assuming you're using one of the various application servers that supports them ? is to let an automated tool like ant build and deploy the file for you.
We used to write the em-dash should be written with the HTML escape ?, but we're now using the the plain-text -- because it's simpler. Also note that the regular hyphen, not the em-dash, is used in hyphenated words like cross-platform

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.

Be consistent in naming and referencing conventions - for example, you don't have to always maintain or omit the parentheses when referring to methods ? toString and toString() are both acceptable ? but pick one style and stick with it.
First-person plural vs. second-person address - many writers use a first-person plural approach when addressing the reader: we implement a custom paint() method for this component. That's OK. An alternative is second-person: you can implement a custom paint() method for this component. It's a little less formal and a little more direct. Use whatever suits you, but choose one and be consistent.
Watch out for periods that look like the dot operator - It can be confusing if one sentence ends with a class name and the next begins with a method, as in:
There are three concurrency-related methods in Object. wait() is the most important one.
Did you realize that was two sentences, or did you read it as "Object.wait()"? Avoid this problem by rephrasing one or both of the sentences, moving the class and method names away from each other.
Do not include a legal disclaimer - We will not include any kind of disclaimer on your article (usually seen as those statements like "The information in this article is not warrented by the author's employer..." at the end of articles on some sties). We are not lawyers and don't have lawyers going over everything we do. Moreover, disclaimers create mistrust by suggesting that the author can't trust the reader to apply the material appropriately, and that the reader cannot trust the author to provide accurate information.

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 examples - blocks of code (including HTML or XML markup, as well as log files and standard output) should be set in a ... block, like this:
```
public String toString() {
    return "This is my toString() implementation";
}
```
Important: These blocks must be 50 characters wide or less ? break lines and indent as necessary. Also, do not number lines, as this impedes copying and pasting the code.
Use ... for class and member names inside of paragraphs - as in "HttpServlet subclasses GenericServlet."
Escape out < and > characters with < and > - browsers will tend to interpret a less-than character as the start of a tag, making the text after it disappear when rendered. This is a particularly big deal when you're showing XML code or Generics, but can still be a problem for Java listings that generate markup or use for loops.
Use italics for file names and paths - as in "Mac users can put lucene-1.7.4.jar into the /Library/Java/Extensions folder to add it to the classpath."
Use a figure reference for images - screenshots, flow charts, UML diagrams, etc. should be numbered and captioned, and your text should refer to the figure by number, instead of saying something like "the screenshot below." For example:
A proper use of an image and accompanying caption is shown in Figure 1.

Figure 1. Example of an image

Important: Images must be no more than 500 pixels wide. If absolutely necessary for clarity, we can link a smaller in-line thumbnail image to a larger version on its own page.
GIF and JPEG are the preferred image formats - GIF is appropriate for synthetic images (screenshots) and line art (like UML diagrams), while JPEG is good for photos. Yes, PNG is great, but older browsers can't handle it, so we can't use it.
If possible, use HTML for lists, tables, and program output - as opposed to using images for these purposes, sticking with HTML will scale better, will work with assistive technologies, will be machine-translatable, etc.
Don't hard-code pixel dimensions for tables or their cells - this makes assumptions about the page size and layout that probably aren't true.
Use a meaningful term for link text, not a URL - instead of saying "this article will be on java.net (http://www.java.net/)", you should simply say "this article will be on java.net".
Don't do "sidebars" - work this material into your body text.
Don't do "footnotes" - link to references directly in your body text. Make aside points in your body text or eliminate them.
Don't open with an
Introduction
header - it's obvious that the material at the beginning of your article is an introduction, so this header is superfluous.

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.