Today, I'd like to take a few moments to focus on something that affects us all, but isn't specifically code related. What I'm referring to is the people who commission the traditional books and magazine articles that you read and learn from every day.

What you might not realize is that publishers have a tendency to enforce surprisingly strict guidelines upon writers.

For those of you who haven't yet contributed to a technical book or magazine - or even some commercial blogs - what you might not realize is that publishers have a tendency to enforce surprisingly strict guidelines upon writers.

• Your article must be this number of words.
• You must provide a total of X images with your article - regardless of whether the content merits imagery.
• Your introduction should be three hundred words.
• Each section of your article must amount to one hundred words, and contain two code samples.
• If writing a book, the full chapter outline must be provided at the beginning of the process, before you've had any time to live with the book, and determine when and how to discuss each topic.
• Worst of all, you must use our ridiculous, unintuitive Word document and template, when preparing your article or book.

The items noted above represent but a small portion of the restrictions that rest upon a technical writer's shoulders. What this translates to is: in addition to deciphering how to best explain considerably complex technologies, a technical writer must also somehow manage to fit their content within the boundaries of a publisher's confusing predetermined guidelines.

For the icing on the case - and to apply yet more pressure upon the writer - a variety of (fairly intense) deadlines will be set, in order to ensure that the book is completed on time. While this is certainly understandable, many times, publishers tend to be too ambitious in the dates they choose, which don't account for the writer's full time job and other responsibilities.

This model is out-dated, and quickly nearing extinction, if it's not addressed and modernized.

Why Do They Do This?

Teaching code is, in many ways, an art.

Before we continue picking on traditional publishers, it's important to first understand why they do this. Consider a magazine with a finite number of pages available for a particular piece of content - say, five pages. If this were the only restriction, it would still prove difficult for the writer. Teaching code is, in many ways, an art. It requires both an understanding of the technology, as well as the ability to explain it in such a way so that everyone can comprehend it. How do you place an abitrary word count on art and explanation? Well, the answer is that you can't - at least not without considerable sacrifice and editing.

Let's continue on; now that we've established that Magazine X may only have room for five pages, the next restriction comes in the form of finding a way to cram your article into a pre-defined layout template, that is, needless to say, not conducive in any way, shape or form to the writing process. This is where the image and per-section word count requirements come into play.

Imagine being told that you need to describe how this piece of code works in 25-35 words. Done? Now, imagine the sacrifices that you'd have to make, in order to wrangle your explanation enough to fit that requirement! Who benefits from this?

It's About Automation - Not the Writer

The rub lies in the fact that these templates and macros don't take the writing process into consideration.

From a non-writer's perspective, it's perfectly understandable why it might be necessary to set these restrictions. Consider the publishers who organize and edit hundreds of books per year. In these cases, it quickly becomes essential - for their own sanity - to prepare templates, and significantly complex Word documents and macros to automate as much as possible.

The rub lies in the fact that these templates and macros don't even begin to take the writing process into consideration. Now, rather than focusing on what's most important (explaining complicated code), the writer is instead forced to place considerable effort and time into deciphering how to use a particular Word macro, or format their document, per the publisher's guidelines.

One of three outcomes can result from a publisher imposing pages of requirements upon a writer, who wants nothing more than to teach a particular technology to others - and, perhaps, pay the mortgage in the process. (If you think the writers of your favorite technical books do it for the money, think again.)

• Acceptance: The writer agrees to the limitations, and does their best to work their way through the process, like a maze.
• Abandonment: After significant investment, the writer ultimately pulls out of the project, due to the effects of an unnatural writing process and deadlines.
• Refusal: Upon receiving the various forms and guidelines, the writer quickly becomes overwhelmed and refuses the contract.

I'm sure you can guess which option above tends to be the most popular.

What's Ideal?

At one point, I had similar requirements for Nettuts+ contributors.

I must admit, at one point, I had similar requirements for Nettuts+ contributors and staff writers. Luckily, the format of a blog naturally makes for less stringent requirements. A per-section word count requirement is silly and meaningless for a blog. That said, I still emphasized word counts, providing images, and using our special Nettuts-specific HTML template, when preparing new tutorials.

Why? Well, for the same reason as why traditional publishers do: my job is easiest, when the article fits my pre-determined layout for a Nettuts+ article.

What I didn't take into consideration was the number of potential writers that I inadvertently pushed away, by setting these requirements. Who honestly has the time to work within the confines of somebody else's template? When time is a precious commodity (especially for those with existing full time jobs and families), these confines serve to be nothing more than a deterrent.

These days, my only goal, when commissioning new content, is to make the writing process for the author as effortless and natural as possible.

• Don't worry about using Microsoft Word, or our custom templates. Use whatever writing tool you feel most comfortable in.
• Don't learn how to make your code fit our special syntax highlighter. We take care of that.
• Don't even think about word counts or image requirements. Certainly, I can't accept articles that are only 400 words, but, in my experience, writers are most effective, when they're far less concerned with meeting arbitrary word count requirements, and more with teaching the content as well as they're capable. If that means the article is 1500 words, or three times that number, I don't care. Just teach it right!

Now that I've matured as editor of Nettuts+, when working with new authors, I only request a Markdown file, which, for those unfamiliar, is a pseudo-language that developers in particular tend to prefer. Markdown takes the visuals and formatting completely out of the writing process, as should be the case - especially in our industry. Alternatively, if they don't feel comfortable with Markdown, they're free to use anything else to get the job done.

Now that I've matured as editor of Nettuts+, when working with new authors, I only request a Markdown file.

Perhaps this method may make for slightly more work on my part, but it absolutely and positively is worth the trade-off. I want our writers to focus on nothing other than explaining complicated technologies as effectively as possible. We'll take care of the rest. If only all publishers adopted a similar model.