Advertisement
Editorials

Publishers: Don't Restrict Writers

by

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.

Related Posts
  • Computer Skills
    OS X
    Introducing Markdown on OS XMarkdown
    Markdown is a popular formatting syntax that lets you easily write plain text that can be converted into a number of other formats; mainly HTML. In this tutorial I will show you how to use the Markdown syntax on OS X.Read More…
  • Code
    JavaScript & AJAX
    Testing in Node.jsNodejs testing chai retina preview
    A test driven development cycle simplifies the thought process of writing code, makes it easier, and quicker in the long run. But just writing tests is not enough by itself, knowing the kinds of tests to write and how to structure code to conform to this pattern is what it's all about. In this article we will take a look at building a small app in Node.js following a TDD pattern.Read More…
  • Computer Skills
    App Training
    How to Effortlessly Create Markdown With TextSoap Textsoap400
    TextSoap is an invaluable utility that I find increasingly useful. It comes with special text cleaners -- little routines for processing text. In this tutorial, I will introduce TextSoap and create a custom text cleaner for processing an article written in Markdown to make it ready for adding into WordPress.Read More…
  • Code
    Articles
    Interview With Jonathan SnookJonathan snook retina preview
    I've met many web developers over the years and the common theme is that they tend to specialize in a specific aspect of web development. They're either designers, JavaScript coders, server-side experts or perhaps a tiny bit of all of them. Rarely do I meet someone who is incredibly well-versed in the full-stack having an amazing design acumen and being able to take a vision and bring it to life, front to back. Jonathan Snook is one of those rare breeds and also an influencer in the web development world. His skills have made him a sought after speaker and writer and afforded great opportunities at companies like Yahoo! and Shopify. He's now venturing into product management and we catch up with him to see how that's going and his advice for anyone looking to jump into that role.Read More…
  • Code
    JavaScript & AJAX
    Handlebars.js - a Behind the Scenes LookHandlebars behind scenes retina preview
    Handlebars has been gaining popularity with its adoption in frameworks like Meteor and Ember.js, but what is really going on behind the scenes of this exciting templating engine? In this article we will take a deep look through the underlying process Handlebars goes through to compile your templates.Read More…
  • Code
    JavaScript & AJAX
    Resources to Get You Up to Speed in Ember.jsEmber resources retina preview
    You've probably noticed a lot of chatter lately about the Ember.js framework and rightfully so. It aims to make it substantially easier to build single-page web apps by abstracting a lot of the complexities for writing scalable and maintainable MVC-based code. And developers are jumping on-board in droves.Read More…