Red Letter: The Ruby Journal Writing Kit

After some delay, the Red Letter writing kit is now available. The
text of the kit is pasted below. You can also find a PDF version of
this kit at

If you would like to propose a feature or write a column, send email
to [email protected].

Red Letter is a technical journal for professional Ruby developers.
Published monthly, Red Letter aims to promote the adoption and use of
Ruby, evangelize new projects, expand the skills of all Ruby
programmers, and spark creativity and conversation.

Each issue of Red Letter includes three feature stories, at least six
regular columns, and a variable number of one-page “lightning”
stories and reviews. Each feature story is at least 3,500 words; each
column is at least 2,500 words; a lightning story is no more than 900
words. Compensation for each type of story is shown in the table below.

Feature: $500
Column: $350
Lightning: $200

Author payments are made within 30 days after an article has been
published (either online or in print, whichever comes first). No
payment will be made without the receipt of a valid invoice. Invoices
must include your name, address, tax identification number, the name
of your article, and the agreed upon fee. Furthermore, invoices must
be submitted within 30 days of acceptance of your final draft.

All payments are made electronically via PayPal unless prior
arrangements are made. Published authors are also awarded one-year
subscriptions to Red Letter.

Articles must be delivered as ASCII text, using simple markup to
realize Red Letter’s typographic conventions.

Each article’s copyright remains the intellectual property of the
author. However, each author agrees that Red Letter will the first
and exclusive publisher of the original content, agrees not to re-
publish the content for a period of 90 days following publication by
Red Letter, and further agrees that Red Letter has the right to re-
use the content perpetually and without limitation.

(The precise legal mumbo jumbo concerning rights of the author and
those of Red Letter will be found in the Red Letter Assignment
Letter, which will be available online shortly.)

The Writing Process

Articles written for Red Letter are developed in four stages:
proposal, outline, first draft, and final draft.
A proposal can be formal or informal, but you must (at a minimum)
identify the topic, explain why the topic is important, and list the
three to five key crucial conclusions you hope readers will reach
after reading the story. Conclusions might sway the reader’s opinion
or represent important technical information.

To propose a story, send email to [email protected]. You may
also propose a series when a single story doesn’t suffice. A series
is particularly effective when you want to introduce readers to
elaborate or complicated material.

Use the outline to realize the arc of your story. A good outline
should include all of the following elements:

  • An objective that explains the goal of the article.

  • A series of meaningful major headings that divide the article into
    thematic or topical sections.
    You can also use major headings to delineate complexity: early
    headings might reflect simplicity, while later headings show gradual
    increases in sophistication. (In other words, you might think of your
    story arc in terms of complexity: motivation, context, review, and
    introductory material first, specifics and proving your conclusions

  • A list of conclusions made in each section.

  • A list of simple sentences that explain, reinforce, and
    substantiate each conclusion.

  • A catalog of figures, listings, and screenshots used in your article.

You must complete a proposal and an outline and have the outline
approved before you begin writing.
The first draft is a complete article, and should very closely
reflect your proposed outline. The prose in the first draft should
achieve the stated objective and relay all of the conclusions. It is
especially important to bridge smoothly from one section to another.

The first draft is also an opportunity to engage with your editor.
Embed questions in your text (using brackets) if you want
clarification, direction, or critique.

If a first draft varies greatly from the proposed outline or requires
considerable editing effort and rework to meet Red Letter standards,
your article may be cancelled. The decision to cancel an article is
at Red Letter’s sole discretion. Articles may be cancelled after your
first draft is accepted and before publication. In that case, you are
entitled to a “kill fee” equal to one-half of the agreed upon fee.
(If you fail to complete a final draft and your article is
subsequently published nonetheless, you are entitled to only one-half
of the agreed upon fee.)

To provide paid subscribers with early access to all Red Letter
content, all drafts are made available on a protected portion of the
web site. Readers may comment on drafts.

The final draft is a finished story, including all figures, images,
code, mark-up, and prose. The final draft is edited for clarity,
punctuation, style, and is prepared for publication by the pre-press

Writing Schedule

Once a proposal is accepted, your outline is due one week later.
After the outline is approved, a first draft is expected within four
weeks. After receiving feedback on your first draft, you have one
week to make all final changes and submit all materials (code,
figures, images, etc.)

Writing Tips

Articles in Red Letter should be clear, direct, and eminently
readable. Write informally, addressing the reader as “you.” Use
contractions, humor, personality, and good style to engage your reader.
Here are some other helpful do’s and don’ts:

  • Do write in present tense and in active voice. Be informal, but

  • Do use line numbers to refer to code in listings, especially if a
    listing is particularly long or complex.

  • Do use sidebars to provide additional exposition that would
    ortherwise detour the attention of the reader. Sidebars are useful
    for lists of references, project histories, technical minutiae,
    warnings, and more.

  • Do provide all of the information required to explain your topic.
    If necessary, refer to existing Red Letter articles to provide
    additional information. You can also refer to other articles on the
    web, as appropriate.

  • Do provide URLs to all projects, products, sites, and references
    you refer to in your article. Place the URL in parentheses
    immediately after the first reference to the resource.

  • Do provide pointers to additional reading, if appropriate. You can
    also propose exercises or even quizzes at the end of your article to
    encourage further experimentation. (Please provide solutions as well.)

  • Do write a fun, short biography for your byline. Please provide an
    email address or URL where you can be reached. You may also send a
    (tasteful) icon to include in your bio.

  • Don’t write in passive voice. Be direct and give the reader
    instructions. (For example, don’t write “Clicking on the button opens
    the window.” Instead, write “Click on the button to open the window.”)

  • Don’t write sentences that begin “Please note that”.

  • Don’t waste valuable space repeating material that’s already
    appeared in Red Letter.

Miscellaneous instructions

If your article includes other assets, be sure to follow these
production specifications:

  • Screenshots must be provided as PNG or JPG images, and should be
    captured at the highest screen resolution possible.

  • Code and other resources that accompany your article must be
    provided in a tarball or gzip archive. Include everything required to
    reproduce the application or system described in your article.

  • If you would like us to produce a professional-looking figure or
    illustration, please email or fax a readable sketch to your editor.

Writing Opportunities

Red Letter is currently looking for writers to helm monthly columns
and create feature stories. Columnists are expected to create a plan
for and write at least six columns. Columns are due on the first of
every month and 30 days prior to the publication of the next issue of
Red Letter. Available columns include:

This Month in Ruby
Stay tuned to “This Month in Ruby” for a monthly summary of releases,
updates, and milestones.

The Ruby N.
You keep hearing about how great Ruby is – it’s time to try it.
Cross over into Ruby with this monthly hands-on guide.

On the Fast Track
Ruby on Rails is revolutionizing the development of Web applications.
Stay on the “Fast Track” with these expert tutorials.

Expand and polish your skills with some expert advice and insight
from the best and brightest Ruby developers.

Shiny Gems
Before you reinvent that wheel, try one of the great packages that
extend Ruby.

In addition to columns, you may propose a feature story or consider
creating a proposal and outline for any of the following topics:

  • The Top Twenty Ruby P.ming Mistakes

  • Hardening Ruby Applications

  • Building Ruby Applications with rake

  • Ten Debugging Tips

  • The Future of Ruby

  • Developing Ruby Applications with the Eclipse RDT

You can also be paid to organize the community and events pages and
chair the monthly Ruby quiz. Send proposals, and inquiries to
[email protected].

Typographical Conventions

The conventions for type in Red Letter will be published shortly.

Sam Flywheel
The Red Letter: The Ruby Journal
email: [email protected]
aim: sam.flywheel
skype: sam.flywheel