Editorial Missteps of 2002

		Print
		Email weblog link
		Blog this

chromatic
Jan. 17, 2003 11:12 AM
Permalink

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:

- it's not linux-only. It was made to portable, and its main targets during development were windows, linux and linux/ppc. It was mostly developed on windows, actually.

- first picture: "deathmatching with cube" (picture shows single player)

- "A future release will allow adjustments to the engine's "camera" perspective". This entire paragraph is completely taken out of context and wrong. He simply asked me wether it was possible and I said yes, then he makes a big thing out of it.

- "with similarities to the lightning gun in Quake III": I never said quake 3, only ever quake 1.

- second picture: "Dynamic lighting from several sources": this picture does not show dynamic lighting at all, just big particles.

- "Most of Cube is van Oortmerssen's own original work, but it includes pieces from other projects" not true, unless you call SDL etc "other projects"

- "He built the entire multi-player code": what does entire do there? I build the whole game, so the fact that I made the multiplayer goes without saying.

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!

chromatic manages Onyx Neon Press, an independent publisher.

Comments on this weblog

Return to weblogs.oreilly.com.

Weblog authors are solely responsible for the content and accuracy of their weblogs, including opinions they express, and O'Reilly Media, Inc., disclaims any and all liabililty for that content, its accuracy, and opinions it may contain.

This work is licensed under a Creative Commons License.