The //comment FAQ!

Q. What is this book you keep going on about?

A. The people at Apress have asked me to serve as editor of a book tentatively titled //comment: The Best Software Essays of 2004.

Q. How are essays chosen?

A. Essays were nominated by the readers of Joel on Software. I also picked some of my own favorites.

The goal of this book is to encourage better writing about software by highlighting some of the best writing of the year. What I'm looking for is simple: good writing. Writing that is engaging, because it is funny, clear, or important, and writing that draws you in. I want the experience of reading about software to be better. I want software developers to learn how to write things that people want to read, because communicating is one of the most overlooked skills in software development.

The final decision of what to include is mine and I take full responsibility for the shoddy choices I've made.

If the first edition of this book sells well enough to justify a follow up next year, I'm hoping to have a committee.

To qualify, essays have to be written "around" 2004. Some are a little bit older, which will be ok for this first edition as long as they are still timely, but in future years I'll be a bit more strict.

Q. How is the book organized?

A. First I'll write a brief foreword.

Then the articles will appear in strict alphabetical order by author's last name.

Each article will be introduced by me, sometimes with one sentence, sometimes with a paragraph or two. This will be my only chance to interject my own opinion. After that, the author gets the last word. Yes, in many cases, I've chosen essays that I happen to disagree with vehemently. If they're good writing, I still want to publish them. My introduction may reflect my personal opinion but the author always gets the last word and I won't interfere with their writing.

I may insert editor's footnotes which are usually meant to explain technical concepts that may not be familiar to the average reader, and to explain things that were hyperlinks to outside websites or references to previous web articles in the original. Footnotes will not be used to add my editorial opinions. The original author can and should replace hyperlinks with footnotes explaining what's going on to the reader. My opinion will be confined to the introductory paragraphs. Editors footnotes will end with [--Ed.]

The first page of every essay will have an unnumbered footnote at the bottom which says "This work originally appeared on the web on [DATE] at http://..." and, if necessary, "... and has been [substantially] edited for this edition." In those rare cases where we're reprinting magazine articles instead of things on the web, we'll refer to the original magazine article in MLA style.

Finally there will be a big ol "about the authors" section at the back, also in alphabetical order, with up to a paragraph of biographical information about each author as submitted by the author themselves.

Q. Will essays be edited?

A. I would like every essay to be copy edited, at the very least, to get spelling checked and punctuation up to the standards of the printed word as opposed to the rather informal standard of personal blogs, however, if an author vehemently requests that their essay be printed exactly as it appeared on the web, we will honor this request, even going so far as to use a particularly silly font for that one essay if that's what the author wants!

Depending on the essay I may ask the author to make changes that reflect the shift from web to print. For example, essays which rely heavily on some other essay available only on the web may need to be somewhat rewritten so that the other essay is not a prerequisite. An essay that starts out as a reply to another essay, where on the web a hyperlink was sufficient to "incorporate by reference" the original, will have to be changed a bit to give the book's reader everything they need to enjoy the essay. I haven't chosen essays which can't stand alone so this will not be a big problem.

In a few cases the author and I may agree that the essay deserves to be expanded or rewritten for the written format. For example some of the articles appeared on the web in very terse or informal format and the writer may wish to expand a bit. This will probably be OK as long as the essay doesn't lose whatever made it interesting in the first place.

Q. Will authors retain rights to their works?

A. Apress will ask each author for nonexclusive rights to publish the work worldwide and in translation. Being nonexclusive means you can and should keep your article on the web or publish it anywhere else you see fit. Beyond that IANAL (I Am Not A Lawyer) so authors should carefully review the legal agreement Apress sends them.

Q. Is there a prize?

A. For each essay published the author will receive a purely symbolic $200 prize and five free copies of the book when it comes out. Authors will be entitled to purchase an unlimited number of additional copies at 60% off the cover price directly from Apress.

We're also designing a little trophy logo icon thing that authors can display alongside the original article on their website.

Q. What happens after an essay is selected?

When an essay is chosen, I'll chat with each author to discuss if there are any major changes we agree should be made for the print version.

Authors will have a choice of what we call the "long workflow" or the "short workflow." If an author wants to have a hand in the copy editing of their work for print and wants to approve every step of the process from web to print, they should opt for the long workflow. If they are happy to let our copy editors fix up their spelling and punctuation and are willing to trust the result in exchange for less work, they should opt for the short workflow.

The long workflow:

A) Apress sends author contract
B) Author signs and returns contract
C) An Apress editor will convert the document from HTML to a Word document in official "Apress" format and using Apress styles. At this point NO CHANGES WILL BE MADE, not even obvious spelling corrections.
D) The document will be sent to the author for review.
E) Author makes any changes necessary, replacing hyperlinks with footnotes, etc. and sends it to Joel.
F) Joel adds the editor's footnotes and sends it back to Author to review and accept or decline his changes.
G) Author sends this "first draft" to Apress copy editor.
H) Simultaneously, Joel sends an introduction to the copy editor.
I) Apress copy editor reviews style, punctuation, spelling, etc. of the essay and sends to author.
J) Apress copy editor reviews style, punctuation, spelling, etc. of the intro and sends it to Joel.
K) Author reviews copy editors changes and changes back anything they don't like
L) Joel reviews copy editor's changes in intro and changes back anything he doesn't like
M) Author sends document back to copy editor, who finalizes the document
N) Joel sends intro back to copy editor, who finalizes the intro
O) Pages are laid out -- the intro is combined with the article for the first time
P) Laid out pages ("galley proofs") are sent to the author as PDFs for final review
Q) Author sends them back with any emergency changes noted. At this point it is too late to change the pagination and Author will not be permitted to change anything in Joel's introduction.
R) Apress finalizes and publishes the book.

The short workflow:

A) Apress sends author contract
B) author signs and returns contract
C) An Apress editor will convert the document from HTML to a Word document in official "Apress" format and using Apress styles. At this point NO CHANGES WILL BE MADE, not even obvious spelling corrections.
F) Joel adds the editor's footnotes and introduction and sends it back to Apress.
I) Apress copy editor reviews style, punctuation, spelling, etc. of the intro and essay and sends it to Joel
L) Joel reviews copy editor's changes in intro and changes back anything he doesn't like
M) Joel sends document back to copy editor, who finalizes the document
O) Pages are laid out -- the intro is combined with the article
R) Apress finalizes and publishes the book.

My new book is here! Apress has just published a new collection of 36 essays from Joel on Software, aptly named More Joel on Software. Get yours today! Available from Amazon.com or wherever fine cheese is sold.

About the Author: I’m your host, Joel Spolsky, a software developer in New York City. Since 2000, I've been writing about software development, management, business, and the Internet on this site. For my day job, I run Fog Creek Software, makers of FogBugz—the smart bug tracking software with the stupid name, and Fog Creek Copilot—the easiest way to provide remote tech support over the Internet, with nothing to install or configure.

Enter your email address to receive a (very occasional) email whenever I write a major new article. You can unsubscribe at any time, of course.