As a jaded editor, I’ve had this conversation so many times I feel like I could spew it out backward and make it sound like a Black Sabbath recording. Most people’s experience with writing is for school. Sadly, the standard for school and for publishing in the rest of the world is hugely different, and no one tells you that until you’re sitting there with your first rejection notice in your hand, or worse, some relentless editor has doubled the number of pages with comments and corrections and you’re considering developing a drinking problem.
Here’s the difference in a nutshell: in school, you show what you know and try to impress; in publication, you teach someone who does not already know the material.
This means that in school, the teacher either knew all of what you wrote or most of it, unless you wrote papers in the hard sciences and set out to discover something new. But even then, your reader was someone very versed in the topic and was pretty much just checking your work. When you’re writing for a technical publication, whether it’s marketing material, an introduction to a subject, or deep development, you are teaching something to someone who doesn’t know as much as you do on the subject, or at least has not had your identical experience.
In school, you used your whole cadre of polysyllabic verbiage, replete with as much Latin as possible; for publication, you run screaming from these same things. Microsoft’s editorial department has a motto: “Dare to be dull.” The idea in technical publishing is to be clear, not to impress. And frankly, even your old organic chemistry teacher wasn’t particularly impressed with your long words. (I know. I was a peer editor. I wasn’t impressed.)
In school, you provide a history for the concepts on which you are about to propound. This is mostly to show that you did the work and that there is precedent for your ideas. In publishing, please oh please don’t provide a history. No one will read through it, and it’s likely you’ll lose your readership before they even get past the introductory paragraphs. You do need to provide context—you can’t just start building code without telling us what we’re trying to accomplish or what products you’re going to use. But don’t tell us about version 1.25 and back in the 80s and so on. It isn’t germane to what you’re writing about NOW.
In school, you can quote people and borrow their ideas (in your own words, of course), as long as you provide a list of your sources at the end. In publication, you need to write entirely original material, or use only a very small amount of someone else’s work, and you need to properly attribute borrowed material right there where the quotation is. You can’t wait to the end and say “thanks” to the person whose work you’ve used, because that’s like calling the person whose wallet you stole and telling them what you spent the money on. Attribution means that you say where it came from right up front (“list provided by the Microsoft Development Team,” or “code is an excerpt from Chris Kunicki’s Error Counter) in the text before or immediately after you do it.
In school, you’re asked for a paper of a given length. As long as you don’t drop seriously under the limit, no one is really going to dock points for coming in long. But in publishing, going over has dramatically bad consequences. In a magazine, the pages for text and advertising are allotted so that one pays for the other, and the amount of paper purchased for the printing is specific to the number of pages expected. When you come in long or seriously short, you’re going to get so drastically edited that you won’t recognize yourself, and there won’t be a rush to rehire you, even if you wrote amazing stuff. In a book, the same situation applies, only without the advertising. Book printers allocate a certain amount of time and space on the printing press, and changes can bump your work right out of the queue. The waiting list is usually something like three months, so your book will lose a large percentage of its potential sales. In magazines, books, and on the Internet, your overlong piece uses up more editorial and layout time than was allocated, and the person getting financially screwed is usually the editor. You really don’t want an irritable editor, now do you?