Thinking out loud about article development

A couple of authors have me rethinking the process for doing the feature articles here on java.net. 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 java.net (or ONJava... I edit both sites, though most of this is java.net) 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 java.net, 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 java.net 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 java.net 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 java.net 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.