House of Fusion Writer Guidelines

The following guidelines do not need to be implemented in every detail in all of your writing. We'd by far prefer to get great technical content and edit the English in it than to try to put great technical detail into awesome writing.

So don't sweat it if you always hated English or even if English is not your native language. We can work with you. Honest. We just want you to know what we try for in advance. If you can get there yourself that's awesome, but almost nobody can (including our editors, when they write for us). So if not, the following may explain some of the editing you see in your work.

We do think it's important to get correct technical detail from you though. It really matters what the name of that class is. This is code, and computers aren't good at guessing. So we need to see from your writing who (or what) is doing what to who (or what). If not, we may need to ask you questions, to avoid editing in errors. This last concern explains why we may ask you to review an edited copy of your article, which is your work after all. We want to be sure that you agree with it in its final form before we put your name on it.

By the way, if you would prefer that we simply make the changes without markup, please do let us know as this saves us work. ;)

Our editing process covers spelling, grammar and readabilty. This last category may confuse you. If the sentence does not contain an actual error, then why change it?

Because we want the articles crystal-clear and easy to read, is why. A second set of eyes will often help achieve this.

Also, writing a tutorial requires slightly different skills than writing a statement of work or a security policy or a memo about the budget. People who normally write such documents can get into speech habits that they no longer notice. In addition, certain phrases go through phases of popularity, and at times we may edit them out just to avoid having every single article in a given issue talk about how good an addition x is to a developer's toolbox, for example. We also try not to leverage x to do y anymore. It's been done to death.

However, the reverse applies as well. We're going for an overall cumulative effect, so almost none of the individual changes absolutely must be changed. So if any given edit makes you wince because the result doesn't sound like something you would say, or because you just don't like it, or *especially* if it contains an error of fact, please say so.

Readability is important but accuracy trumps it every time, and this includes accuracy in reflecting your voice and personality.

Readability

In general we strongly prefer active tense to passive. For example, "The code runs" makes better reading than "The code is run". Abstract concepts such as application architecture don't always fit well into active tense, and we do know this. Where possible our rule of thumb says we like to see about 75% active verbs, but if we can't make a sentence flow smoothly without using "is", then we use "is", end of story. The point here is readability.

We also try to reduce the sentence complexity where possible, especially in very technical material. This means that if we can express an idea as two sentences rather than one sentence that contains a parenthesis, we'll usually like the two-sentence solution better. If we can avoid subordinate clauses we will. For example, "The reason that we do this is" may become "We do this because". This link may help explain why. We don't use a formula, though; we just make small changes that nudge the article towards greater readability without, we hope, changing your words too much.

The changes may not look small, by the way, but word order is the most frequent reason for a change. Often the same words get restructured so that "the article is read by the reader" becomes "the reader reads the article". This change requires deleting then re-entering several words, you notice. We use strikethrough to show deletions until we have a final, approved version of the text, so the article may look very marked-up yet contain mostly the original words. If you find the article hard to read we'll send you a version without the markup, but a lot of authors want to see what exactly changed, so we default to that.

Some Specific Style Guildelines

Never use the acronym CF; it's always ColdFusion.

"The first thing we will do..." — Avoid "The first thing we will do is" if you don't later have a second thing.

Adjectives made up of two words (low-level, just-created) take hyphens for the sake of readability.

Section headers follow the standard English convention for titles: important words capitalized.

Quotes: Avoid quotes to indicate irony if possible. Quotes are used to cite actual words spoken or written by a source. Or perhaps to indicate a thought. We use italics to emphasize.

Captions for figures: Initial cap on all important words. (Designer does format, so don't worry if you forget.) Format: "Figure 1: It Looks Like This"

Code listings — Tahoma for Fusion Authority; Myriad Pro for Flex Authority. Don't worry about the font as the designer does that. Titles in bold with the format "Listing 1: A Name that Summarizes the Code in the Listing". One line of code is not a listing, but anything longer is. One line gets broken out in code format with a blank line above and below.

Classes — bold (all languages, Flex, Flash, ActionScript, Java, whatever)

ColdFusion components — bold

Interface components that are also classes (ie Button) are only capitalized if the sentence clearly refers to the class. Sometimes a button is just a button. (Flex Authority only)

• Subscribe
• RSS

• Editorial
• Specials
• Community
• News
• Tech and Tags
• Views
• Reviews
• Techniques
• Security
• Best of ColdFusion Talk
• Knowledge Base
• Blog Watch

• Tipical Charlie