Structured Writing - An Outline

Samuel Beckett once wrote, "Nothing matters but the writing."1 More recently, Jakob Nielsen said "people are on the Web for the content." While we all agree that content is important, good writing doesn't happen automatically. It takes planning and organization. If you're intimidated about writing, or just don't know where to start, this outline will help.

Validation

or, Why You Should Keep Reading

While writing and public speaking are arts, they are also sciences. You can learn to present your ideas in a way that others will find usable and interesting, even if you don't have "the gift of gab." Once you've got the basics firmly in mind, as you practice you'll likely notice improvement in the more artistic aspects of your writing, too. But first things first — how about step-by-step instructions for writing a "how-to" article?

Preparation

or, What Should I Already Know?

While spelling and grammar are grossly overrated as an indicator of personal worth or general intelligence, they are important when writing to teach or convey other important information. A simple text editor is great, but if you have any concerns about your spelling (yeah; right there — you know who you are) use a spell-checker. Egregious errors in spelling will distract from your point and complicate the transfer of information to your readers. Grammar is less critical. Unless your speech is frequently misunderstood by friends and family, just write like you speak. Worried about sentence fragments and split infinitives? Forget about it. Be natural and you'll be fine.

To get started, here's the most basic outline, for writing or public speaking:

1. Tell 'em what you're going to tell 'em
2. Tell 'em
3. Tell 'em what you told 'em

I'll expand, of course, but if you have that brief outline in mind, it's much easier to get a mental picture of the overall process.

The Meat

or, Now We Get to the Point

This time, a little more detail:

1. Introduction: State your point, in two or three short sentences with virtually no detail.
2. Validation: Why should anyone care? Tell them what value they'll get from reading the article — a practical coding tool? Professional advancement? Whatever; even if it's just an interesting quirk of web design.
3. Preparation: What do they need to know to understand the meat of the article? Mention the languages and platforms they should be familiar with, the hardware you'll be addressing, whatever they might need beyond an inquisitive mind and a text editor. If that's all they'll need, state explicitly that "no previous knowledge is assumed" or something like that.
4. The Meat: One step at a time, give 'em the meat. Lay out exactly how you would reproduce your results. Do you build each piece independently, or do they grow simultaneously? Is it CSS, then ASP, then HTML? 'First plug in THAT, but remember not to put your hand THERE or you'll break it.' Go through the process, making notes on every step you do, no matter how tedious or obvious. Believe me, "obvious" isn't. Unless you're sure your grandmother would understand it, explain it. Line by line. If you can find someone with very little experience (not "no experience") to try to follow your explanation, you're golden. They'll find most of the errors and invalid assumptions.
5. Application: Sure, we told 'em in step two what they'd gain from all this, but that was in generic terms. Now, show a practical application, either current and real life, or something wild and futuristic. Or, show what the next question is — maybe there's no way on earth it's useful, but if someone could solve the next problem, they might get to a practical use. Tell 'em what the next logical step is.
6. Review: State, in two or three short sentences what you taught them.
7. Call to Action: Explicitly invite your readers to do something with what you've written; build the box, try the code, look for a practical application, work on the next logical step.
8. Bibliography/Notes: If you have any references, either stuff you used to derive your content, or places where readers can get more info, provide links. If they're books, provide complete info, and maybe even a link to Barnes&Noble or Amazon. Make it easy for folks to follow up.

Application

or, So, You're Saying, I Can Write?

These guidelines should be generic enough to apply to more than just writing a 'how-to' article. School reports, letters home, the Great American Novel; if you structure it right, you'll get your point across and your readers will benefit.

Most folks are paralyzed with terror when faced with public speaking. If you know what you're going to say, it really helps keep the panic to a controllable level. Putting it in a structured format which follows a logical thought pattern will make it easier to be extemporaneous instead of just reading a script.

Review

or, Could You Repeat That, Please?

Following this structured approach won't make you a Beckett or a Hemingway, but it will help you organize your thoughts to enable you to present them in a logical, orderly fashion. It will help ensure that you don't miss important points, and will assist your readers to understand and retain your information. If you're writing to teach, that's what it's all about. So, tell 'em what you're going to tell 'em, then tell 'em, then tell 'em what you told 'em.

Call to Action

or, What Now?

If you're an absolute beginner, you'll probably need to gather more experience before you're ready to write for public exposure, but you can still benefit from these guidelines. Next time you write anything see how well they fit. The important thing is to practice. Writing in a daily journal or weblog is one way to hone your skills in an informal arena.

If you're a more experienced writer, use these guidelines to review your past efforts. With the passage of a little time, it's more evident whether you successfully conveyed you thoughts.

Finally, every good writer has a good editor. It can be very helpful to have your text reviewed by someone whose writing you understand and appreciate. Don't feel compelled to integrate every suggestion, but do listen to constructive criticism.

Bibliography/Notes

or, Where Did That Come From? Where Can I Get More?

This article barely scratches the surface. Here's where to read more about good writing:

• No writer should be without William Strunk's "Elements of Style" which is now available online. But buy a hard copy for your desk for scribbling notes and highlighting the good stuff.
• Get a good dictionary; a big fat one that gives the etymology of the words. Find out where words came from, and you'll make better use of them. Again, dictionaries are available online, but get one for your desk. You'll use it.
• Roget's Thesaurus. A complex tool, but worth the effort. It will help broaden your vocabulary, making your writing more interesting and varied. It's also the best tool when you're looking for just the right word for accuracy's sake. Yet once more, available online, but buy one anyway.
• For the serious writer, 'The Chicago Manual of Style' or 'The New York Times Manual of Style and Usage' will provide enough detail, clarification, and aracana to satisfy your writer's lust. Note that these weighty tomes are aimed primarily at those writing or editing for print, and include much information not specifically applicable to writing for the web.

Happy writing.

1 Samuel Beckett quote at Bartleby.com