Skip to main content

I Wanted to Tell You

Posted by editor on August 9, 2006 at 8:32 AM PDT

Thinking out loud about article development

A couple of authors have me rethinking the process for doing the feature articles here on Let me tell you how it works now:

  1. The author sends in a proposal for an article. My guidelines for this are to send a simple e-mail of 5-10 lines that establish:
    1. What the article is about
    2. Why it matters
    3. What specific things will be covered in a 2,000-word article that deliver on points 1 and 2
  2. If the proposal is good, I'll set up the author with our writer's guidelines, which describe our "do's" and "don'ts" (how to format code examples, how to cite figures, why you should almost never use the word "relatively", etc.).
  3. The author sends in a first draft.
  4. I edit the draft and (usually) send it back for some changes. Sometimes articles are ready to publish after a first edit, but usually not.
  5. Repeat steps 3 and 4 until a final draft is ready
  6. Load the draft into our publishing system. From here, our producer (hi Craig!) formats the article to add things like the images, page breaks, and table of contents, and ties into automated stuff like the link to the author's bio.
  7. A copy-editor (hi Jamie and Jill!) sweeps over the language and makes sure everything's grammatical.
  8. I click a button to publish the article, and do a few more steps to get it on the front page

This ends up being a very mail-intensive progress, with only as much structure as I am able to consciously enforce myself. For example, the screenshot below is a look at my "Editing" folder, with one folder for each (or ONJava... I edit both sites, though most of this is article. I've blurred the names of authors and articles for purposes of privacy and novelty.


Yes, I do have a lot of articles to work on right now! The orange labels on some of these folders means the article has been sent out for rewrites and has not returned. Clear means completely untouched (by me), yellow means "rewrite returned; needs re-edit", red means "waiting on author for something", and green means "ready to publish". Inside each of these folders, I keep a history of all the various drafts, from the first I received to the "final" that gets uploaded to, as folders named "edit 1", "edit 2", etc. Odd numbers are the authors' drafts, even numbers are my edits.

This scheme is adequate, but I have to be consistent to keep a history of all the versions. Also, all my communication with the author is in the form of e-mail, so if there's something I need to remember about an article or a specific draft, I need to go look it up there.

Mail is fun too, because of all the hazards of sending articles, images, and code back and forth in e-mail. Some authors' mail gets flagged as spam because their hosts are on O'Reilly's blacklists, and still others are flagged as spam for no discernable reason. Sometimes the HTML-formatted articles get inlined into a mail message, and I have to save it as raw source and clip out all the MIME headers and unrelated contents to get just the HTML. Every author needs the writer's guide to get started, but some sites (GMail in particular) reject my ZIP attachment (see Zip Considered Harmful?), so I have to keep a tar.gz handy. And I've always meant to get those guidelines posted publicly, so I don't have to keep fighting that battle, and so I can get a "wish list" of article topics in a public place, where potential authors can see them before making a proposal.

Now look at the upper right, to the folder called "subverted-authors". That's where I'm working on an article from John Smart, who wants to work via Subversion.

That idea, plus the need to get the guidelines and wish list up where people can get to them via the web gave me an idea:

What if I moved the entire article development process to a project?

With the project's web space, I'd be able to post basic HTML docs like the writer's guide, topic wish list, and HTML template. Then the authors would basically be committers on the project. For each new article, I'd create a new folder within the project's source files, and the author would svn add his or her HTML, images, and sample-code zip's there. I'd be able to edit the file directly (instead of managing folders on my machine) and make comments in the HTML source, then svn commit the edit back to the author. I wouldn't have to manage the history, since Subversion would do it for me.

This would also be trivially easy for editing on the road, as opposed to my current pre-trip to-do of moving folders from G5 to PowerBook.

Writing and collaborating via subversion isn't a novel concept, of course. Josh and I wrote Swing Hacks with Subversion, with one folder for each hack's code, then folders for the chapters as we started writing everything up and swapping rewrites with our editor.

Are there downsides? Well, a project's source repository is public, so anyone would be able to see the works in process -- a lovely, open idea until and unless someone gets sensitive over strongly critical comments in an edit being public knowlege or, worse, some other publication grabs in-progress works and publishes them without permission (or finished editing). But then again, maybe we'd have a public project for hosting the introductory docs, and a private or invisible-to-non-committers project for the actual article development. Somehow this could be made to work.

Are there authors who wouldn't be comfortable using Subversion? Probably. Every now and then I get authors who write about writing webapps but can't or won't write HTML, so it's certainly possible I'd have to hold a few hands of first-time Subversion users.

Still, there's an appeal here. There's a lot you can do with a project, and I'm starting to think that the site's tools might do everything I need, even for developing something other than code.

So, authors and potential authors, what do you think? Would you be open to swapping drafts with Subversion instead of e-mail? Write a comment with your thoughts.

Lots of people complain about the huge size of the JRE download, but who's doing anything about it? Simon Morris gives the issue a thorough rethink in today's Weblogs. In
Desktop Deployment Ideas, he says:
"I've spent a fair amount of time over the last few years writing Java desktop applications, and I've quite a collection of scars to prove it. I know Sun are looking to improve SE JRE deployment in upcoming releases, so here's a few uneducated ramblings to add into the ideas pot."

Kohsuke Kawaguchi shares some JSP frustrations in
Hudson 1.40 and why I eventually said bye bye to JSP in favor of Jelly:
"A little rant about why I don't like some aspects of JSPs. I've never been truly happy with JSP (and consequently any technologies built on top of it, including JSF and things like that.) It felt very anti object-oriented, because in JSP and their siblings, pages are always the king and the data is the servant."

Plumber's Hack 1: Highlighting Sourcy, Evan Summers writes:
"You wanna highlight your code samples for your blog, using Netbeans? Here's some triviawarez to help."

In Java Today,

Issue 252 of the NetBeans Weekly Newsletter is out, with items on how to migrate your JBuilder Project to NetBeans, Visual Mobile Designer tutorials, an interview with the xDesign team, a tutorial on creating a simple Spring MVC webapp in NetBeans 5.0, and more.

Service-oriented architecture (SOA) allows businesses to enable legacy systems and new software products as a service to a wider audience by way of the Internet. Web services technology is the cornerstone of SOA implementation, which involves complex business transactions between various business entities. The article Implementing High Performance Web Services Using JAX-WS 2.0 shows how to implement high performance web services using the Java API for XML Web Services (JAX-WS) 2.0 and provides feature and performance comparisons with the Java API for XML-Based RPC (JAX-RPC) 1.1.

The ONJava blog Mustang for Mac PPC... any point now? says "This blog is about Mustang for the Mac, which is being developed for both PowerPC- and Intel-based Macs. That's kind of interesting when you consider one thing: As of yesterday, Apple doesn't make PowerPC Macs anymore."

In today's Forums,
sbalmos is looking for the
EJB3 equivalent of Handle?:
"Yet another question... Hopefully one of my last. What is generally the equivalent of a Handle for an EJB3 stateful session bean? I'm using the well-known trick of using a stateful bean to maintain server-side state in SOAP, and using a String representation of the bean's Handle as a session ID of sorts. However, casting to EJBObject creates a runtime ClassCastException, so there's no way I can get to the getHandle() method."

Cleanup time for SwingX! In Incubator .. started lib/build cleanup, Kleopatra writes:
"Hi folks, with all those exciting new components/demos I thought it's time to move a bit ahead with the overall cleanup - in the end it should be poop-easy to build a web-startable demo under ther www/demos by simply running an ant task. As a side-effect, I would love to have all the demos point to a shared swingx.jar which should be kept roughly current (naturally, contributors should still be able to decide if they prefer a per-demo custom swingx.jar)."

Things are slow on the news front. News editor Steve Mallett suggests checking out the Register's list of Top 10 technoculture books for the beach. At any rate, today's
News Headlines

Registered users can submit news items for the href=""> News Page using our
news submission
. All submissions go through an editorial review before being
posted to the site. You can also subscribe to the href=""> News RSS

Current and upcoming Java

Registered users can submit event listings for the href=""> Events Page using our href="">events submission form.
All submissions go through an editorial review before being posted to the

Archives and Subscriptions: This blog is delivered weekdays as
the Java
Today RSS feed
. Also, once this page is no longer featured as the
front page of it will be
archived along with other past issues in the href=""> Archive.

Thinking out loud about article development