Guidelines for writing a successful technical article

[Martin Streicher]

Thanks to the many of you that expressed interest in writing for Linux
Magazine.

I shared this article strategy with Eliot of MongoDB fame and thought
it useful for those of you who elect to write for any medium in any
avenue, be it Linux Magazine, your blog, a thesis, or a technical
paper for a conference. I hope you find it useful to organize your
thoughts into prose.

To me, the canonical, hands-on technical story forms a story arc with
a beginning, middle, and end.

* The beginning hooks the reader and satisfies the curiosity of the
entire audience that is reading. After the first 500 words or so, the
reader understands the challenge and why your solution meets that
challenge.

* The next 1000-2000 words explains the solution at a high-level, but
more detailed than the broad strokes of the first portion. Here, the
audience learns how it works, at least conceptually. After this
portion, the audience should be able to reiterate what your software
does and why it is unique. Your audience may then choose to stop
reading, based on the relevance they've now been able to assess.

* The rest of the article is hands-on (and/or more and more
technical). Here the audience is taught how to use the software, at
least in rudimentary fashion at first and then perhaps in great
detail. You might cover installation, first experimentation,
discovery, a tour. Later on you might cover advanced features and
additional customizations possible. If there are tradeoffs to made in
implementation, identify those and pose questions to lead the reader
to make well-informed choices.

* Wrap-up. Discuss future plans and releases; potential pitfalls or
shortcomings and how to address those, point to additional materials
and then close.

In every section, consider what is important to relay first. Don't
worry about how to say it. In general, if you list what is important
to say -- what you want people to learn and retain and is essential
information -- the article tends to write itself.

Here is a further/alternate breakdown:

An article is Problem Statement, Introduction, Description,
Installing, Initial Experimentation, Advanced Topics, Close.

Problem statement: What new trends and problems are emerging that
challenge "traditional" systems? Why do the traditional solutions fall
short. Is the new, emergent class of problems not well-suited to those
applications? What is painful about this new problem that calls for
something better?

Introduction: Explain why your software is a better solution for the
problem at-hand. Enumerate its major features and compel the audience
to continue reading. (This section and the latter section should be
about a fifth of the article.)

Description: Architecture, major design goals and requirements, data
model, and explain what it's good at. Give three-five guidelines or
questions to help the reader analyze a problem to determine if your
solution is a fit for his or her problem.

Installing: How to get this running.

Initial Experimentation: Demonstrate the software at work. Show
essential operations.

Advanced Topics: Show differentiating features at work. Performance
optimization and considerations are good topics. Scaling. Syste,
configuration.

Close.

I hope this helps. I edited Linux Magazine for five years and this is
the blueprint for a successful article.

Martin