Editorial Missteps of 2002
Aside from a few typos and URL corrections, most of the articles we've done worked out really well. I'm proud of all of the authors. I'm proud of the production staff who make sure articles are done on time and look nice and have all of the graphics they should. (Sarah Breen produces ONLamp, Linux, and Java content and does a fantastic job of it. Laura Schmier creates the graphics and manages to impress me at least once a week.)
No one's perfect, and when you put multiple people on a project, the possibility for error can increase. (It can also decrease, but that's a subject for another time.) Someone has to take final responsibility, though, and that's my job as an editor.
This was most evident in Howard Wen's Cube 3D article. It was a good article, but some of our facts were, well, dubious. (Howard and I discussed this the other day and couldn't come up with a reason besides "sometimes it just doesn't quite work".) Wouter van Oortmerssen of the Cube 3D project was kind enough to point out a few facts that were, well, misleading:
Reading through that list is a bit painful. I know which bits of the Howard's text I rephrased into their incorrect states (and I don't know where I got the image captions -- I'll stick to writing headlines). Still, it's a good article about an interesting project, and Wouter's pleased we ran it.
Another article that received some criticism was Adam Trachtenberg's Internationalization and Localization with PHP. Specifically, the example code mixed localization data with code. As Kirk McElhearn, an experienced translator, pointed out, that's a big no-no! You wouldn't want translators to wade through code to change text, and relying on developers to keep things in sync is... well, it's not the fastest way to accomplish things.
My immediate reaction to that criticism was, "Yeah, that's fair". The thing I like about Adam's article was that his PHP object technique means that developers don't have to know where or how translations are stored. They're nicely encapsulated behind a clean interface.
Both Adam and I thought it was obvious that the resources would be stored in files or databases or somewhere outside of the program, but neglected to make this clear enough. Adam's responded in his weblog with more detail.
In retrospect, I think we should be more clear with our example code, often going as far as to say things such as "Detailed error checking has been omitted for space" and "The next step is to add these features before serious deployment". What's obvious after working on an article for several weeks is not obvious to a reader, and we should communicate those assumptions better.
Aside from that, I've seen a couple of cases where example code didn't quite work. The most recent example was where an article wasn't explicit about the necessary version of the target Java library, and the author was very quick to uncover this with the reader.
Overall, I'm very pleased with the quality and breadth of our work. All of our original articles (not book excerpts) feature the Talkback section, so you can leave comments there. You're also welcome to e-mail me with comments, if you prefer.
There, now my plate's clean. Thanks for reading!
Comments on this weblog
Return to weblogs.oreilly.com.