How To Write a Good Howto

[webnote]

 

 

How To Write a Good Howto

Howtos are always useful, no matter the subject they are about. Whether you are trying to contribute to an Open Source project or to attract traffic to your blog howtos can make the things done.

I wrote this list of things to keep in mind while writing a howto based on the howto definition from Wikipedia and my own experience reading howtos

1. Try to keep it short
• Be specific. Howtos are supposed to be a guide to complete some specific task so don't discuss other topics, even if they are related. This take us to the next point
  
• Leave irrelevant details for appendices or another document. Details tend to distract the reader
  
• Divide it in several files if it has to be long and for online reading
  


2. Make it easy to read
• Be informal. Imagine your reader in front of you
• Highlight important information. Many readers just scan the document looking for a specific piece of information
  
• Summarize and categorize. This not only helps your reader to find what they're looking for faster, but helps you to organize your ideas while writing too
  
• Use list and sections. This helps you to achieve the previous point. The entire howto can be a list if you're writing about a simple subject (like this)
  


3. Use visual resources
• Use images or videos. They can save you a lot of words, but use them sparingly because there are a lot of people using slow connections. However, video howtos may be the best choice for some complex tasks.
  


4. Keep it simple. Maybe the most important point and summarizes all previous things. Howtos are intended to make things clearer, after all
• Use technical terms only when it is necessary
• Build a glossary of technical terms or link them to a wiki page that explain it
  

Finally, if you're writing rather formal linux related howto give a try to this HOWTO Generator, it can save you some work.

Have other tips? Please share them with us in your comments. I'm not an expert and this list is not intended to be complete.

Technorati tags: linux, howto, documentation, blog, blogging, writing, list