Tips For Writing A Good 'How To' Blog Post

1. Include screenshots & videos. Almost all good “how to” articles include a few screenshots, especially if the instructions are more than just a couple steps or the interface they are using is very complicated. Keep in mind that most people will probably just scan through the screenshots, and will not read every word. In fact, one of the very few well-documented facts about the Web is that people tend to spend very little time reading a page. Instead we scan them looking for words, phrases, or images that catch our eye. So if your audience is going to act like you’re designing billboards instead of finely crafted literature … design great billboards. Your objective should be to minimize instructions as much as possible by using an appropriate number of self-explanatory screenshots. Each screenshot should be as small as possible and only contain enough context for the user to understand what is being shown (i.e. what page, section, or window you are referencing). You should callout important things directly in the image itself, not just in text on the page above or below the image (remember they probably aren’t going to read that stuff). The image should be always be placed inline, as close to the related content as possible. Alternatively, you could make a screencast or other video, which walks through the process. Videos are especially helpful when it would take more than 5 or 6 screenshots to illustrate the steps necessary. Videos also allow you to add some instructions as a voice-over, which is more likely to convey the information rather than hoping people will read the instructions. Just try avoid long pauses in the video where you are speaking, but performing any action on the screen (if that happens people will likely fast forward past it).
2. Omit needless words. The main thing to remember about instructions is that no one is going to read them – at least not until after repeated attempts at “muddling through” have failed. And even then, if the instructions are wordy, the odds of users finding the information they need is pretty low. When instructions are absolutely necessary, cut them back to a bare minimum. E.B. White’s 17th rule in The Elements of Style: “17: Omit needless words. Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts.”
3. Make specific phrases they will look for bold. If you are referencing the specific name of a button, link, menu option, or the title of a particular section, textbox, configuration option, etc … make that text bold. Often times when someone is following directions they have the instructions up and are reading through them as they are actually performing whatever the instructions are about. They will be continually doing a context switch back and forth from the instructions to the application. For example, they might read an instruction that says “When you are finished click the Submit Changes button.” Making the text bold draws attention to the specific phrase they need to look for and has imprinted that information at a deeper level than the rest of the text. Also, many times they might read the instructions, transition to the other application, and then think “What was the name of the button again?” If the specific text they are looking for is bold, it allows them to find it with a quick glimpse instead of re-reading a section of the instructions.
4. Use Good Titles & Headings. Like a good variable name in software, or a good hostname for a network device ... a title should give you a good idea about what a particular post is focused on (and what it isn't). For example, if there was a blog post about how to attach multiple photos to a single email from your iPhone, you could use the title "How To Send Multiple Photos" or "Sharing Files from iPhone" ... but both of those fall short of encapsulating the primary focus of the post. A title that comes much closer might be something like "How To Email Multiple Photos from iPhone". As a general rule of thumb, if it is a "How To" post ... the title should start with "How To ...". Try to make the title as short as possible, but not shorter. You might also try to think from a user's perspective, "What word would they Google to try to find this information" and then use most of those words in the blog post title. These same principles apply to section headings within a post. Try to strike the right balance between them being descriptive and terse. Remember that users will likely just be scanning the post looking for the part that talks about whatever they forgot or are having trouble with, so good headings can really help them scan through a post quickly to find the section of information they need.
5. Organize the content. Spend a couple minutes trying to think through the most elegant and simple way to present the content. For example, should it just be in one or two paragraphs, an ordered list (i.e. 1,2,3), an unordered list (i.e. bullet points), a table, a chart, broken into multiple sections each with a distinct heading, etc. After you finish the initial draft, review the content again and see if there is a better way to organize the information so it will speak more clearly or concisely.
6. Add lots of hyperlinks. If you ever reference a URL, make it into an actual hyperlink … instead of just typing it as text. In fact, if you are referencing a resource on the web (even one of your own blog posts) or something that has a related page that explains it more in-depth make sure you link to that as well.  Also, instead of writing out a URL directly in the content (which can make the paragraph harder to read), try to simply make the related text a link.  Examples:
   • The DateFormat enumeration used in SSRS expressions is the same as the DateFormat enumeration in Visual Basic.
   • I was recently attempting to build documentation for a few projects using Sandcastle, a free engine provided by Microsoft that compiles …
   • I googled this error, and found this post about multi-targeting …
   • In my recent post on How To: Find Missing Indexes in SQL Server, I showed how …
7. Don't Give More Than One Way To Skin A Cat. Often there are multiple ways to accomplish the same goal. However, if you try to explain all of the different ways ... it typically ends up being more confusing than helpful. If the user figures out another way to do something, great ... but a good "How To" article should focus on the single most common and/or simplest way to perform the operation.
8. Attach appropriate Labels. For each blog post, try to think of all of the categories the content is related to and add a label for each of those. This will help people easily find all of the posts related to a particular subject using the blog's tag cloud.

For more tips on writing good web content, read some of the excerpts from Steve Krug's book Don't Make Me Think.