Writing for the Web

I have been writing opinions and short howtos for my web site for a while now. By carefully researching successful technical documents on the web, I have managed to come up with a basic understanding of which documents will be most useful.

First, there is the issue of presentation. You don't need to have a super snazzy web site (although it helps) with lots of graphics. But you should make sure you have legible fonts and no painful colors. Keep paragraphs short. Long ones are especially hard to read on the web. Break your articles into sections with horizontal rules and section headers. If it's a really long article, use multiple pages and a contents section.

I have frequently had the experience of coming up with what I thought was a great idea for an article, only to end up disappointed. I start out thinking it's going to be ten pages, insightful, and full of information. It ends up being one page, jumping between topics that are barely relevant, and short on useful material. Well things don't always work the same in the real world as they do in your head.

There are a few things you can do. Unless you're an incredible writer with lots of insight, you might want to stick to mostly tutorials instead of opinions. I haven't done that so far, but I have noticed that the instructive articles are the most searched for.

Focused is better than a sampler. In other words, very specific articles are usually more useful than brief overviews of general areas. A number of people have found my latex tips page from google. Usually they're looking for figure help. Notice, there's only a few short sentences about figures. Compare that with latex figures. I expanded that information out into much more. If I really knew latex figure in depth, I probably could have written ten pages. That might be an article worth linking to.

A picture is worth a thousand words. If you're trying to describe something technical, it might be worth even more. Again, go back and compare the last two articles. It doesn't necessarily have to be a picture; any type of diagram can be helpful. Taking the time to make an image, diagram, or table can be time consuming, but it can also make all the difference in the world.

Most of the best content out there wasn't written in one sitting. It evolved over time with editing and feed back from readers. The author may not have even known much of the content when he started. Often you just don't think of useful information until weeks or months later. If you're planning on becoming an expert on some technology, you can start writing about it, and add to it as you learn more.

Sometimes it helps to present something in multiple different ways. For example, this page shows you how to write a basic Fast CGI script in multiple languages. This will also be helpful to readers viewing this page who may only know one of those languages. In some cases, you might also do this for a comparison.

Make source code part of the article. It's OK to have the file as a link. But if you break it into pieces (and format and color it), and cover a chunk at a time, it's a lot easier to understand. Compare this to six pages of text describing a few pages of code that you happened to link to in your resources section.

Give examples and make comparisons. This will lengthen the article and help clarify the original explanation. Make lists and use bold type where appropriate. This will highlight important material. Add humor if you can. Let's face it, technical material tends to be pretty dull. You don't want your audience falling asleep on page one of "An inside look at the design and implementation of the XYZ compiler."