4 Ways To Improve Technical Content On The Web

No matter how many books I read, the Internet is still my primary source of technical information.
Time is my most precious resource.
Wasted time is something I can never recover.

 

It’s frustrating to Google for technical content and to spend time reading pages of information that seems to be pertinent, only to discover that it’s completely irrelevant — because it doesn’t apply to my environment or it’s out of date. What’s more annoying is that this scenario seems to be more of the rule rather than the exception.

Rules 1 and 2 describe what you can do to help your readers assess whether your post is relevant to what they’re looking for. Rules 3 and 4 discuss tactics that will simply make your contributions more valuable.

Rule #1: Date stamp your posts

Change is the one thing you can count on… and in the world of software engineering, you can expect those changes to happen pretty quickly. Information that may have been highly relevant a year ago could be completely irrelevant today. Your reader has no means of assessing the currency of your content unless they know when it was written.

Rule #2: Provide a complete context

Many of the modern technologies we use to develop applications change significantly from version to version. If you’re contributing knowledge that applies to a specific version of Visual Studio 2010 SP1, that information should be prominently displayed near the top of the page. Include as much context as possible. If you’re describing a scenario that exists when running Visual Studio on Windows XP, you should say so. If you don’t know whether the information applies to other OS or application versions, you should say that as well.

Rule #3: Get a peer review

If you’re an inexperienced writer or writing in a language that’s not native to you, ask someone to review what you’ve written for accuracy and readability. I once worked with a very smart programmer who had a terrible time with negation terms in the English language. As a result, we spent countless hours misunderstanding each other because what he said was the opposite of what he meant to say. Your readers won’t necessarily have the opportunity to ask questions about what you meant. If your writing is grammatically correct and easy to understand, they won’t have to.

Rule #4: Avoid using obscure links

Many web sites have been known to restructure their pages, leaving a lot of dead links and bookmarks in their wake. If you use links like MSCDEX May Not Detect Disk Change and the referenced page disappears, your reader still has a title they can Google for to find the new location. If you use links like click here, the only remaining context is the URL itself which is usually not enough to track down the broken reference.