This blog has moved to www.nongeekperspective.com. There you will find new posts
Friday, September 29, 2006
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
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
Add to: del.cio.us | digg | furl | blinklist | netvouz
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
- 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
- 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)
- 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.
- 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
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
Add to: del.cio.us | digg | furl | blinklist | netvouz
This blog has moved to www.nongeekperspective.com. There you will find new posts
Comments:
said:
This is so important if the open source world is going to find a following in the non programmer world. Which it really needs to do if it is to be sustained in the long run.
As a non-geek who administers my own Linux servers, I was just about to give up after years of treading water. Red Hat wants you to take all their training classes, and the "programmer sect" laughs derisively when you do not understand something.
Then I found the howtoforge.com site. One of its operators - who goes by "Falko" - writes the best Howto's I have ever run across. Not every Howto on the site is outstanding, but everyone of his that I have used is truly a work of art. I have already paid my subscription to his site. It is a lot less than what I pay Red Hat and much more effective. I am even learning to love the command line!
Zack said:
Good one! Very rare to find a well written howto.
Posted this at http://www.howtohut.com/howto_write_a_howto
Lv said:
well,can you tell me how to add "Add to: del.cio.us | digg | furl | blinklist | netvouz" at blosspot,thanks,i'back soon.
nongeek said:
tomd:
You're right. A good documentation is very important and howtos may help any project to build a good documentation.
zack, sandeep:
Thanks!
lv:
You can read about it here
André Simões said:
Can I translate this post to the Portuguese (PT-BR) and publish the translation on my blog, giving all it credit to you and linking to the original post?
said:
Can u review the Howtos I wrote in my blog? I wanna know how they are.
http://www.theusefulblog.com
Post a Comment
<< Home
said:This is so important if the open source world is going to find a following in the non programmer world. Which it really needs to do if it is to be sustained in the long run.
As a non-geek who administers my own Linux servers, I was just about to give up after years of treading water. Red Hat wants you to take all their training classes, and the "programmer sect" laughs derisively when you do not understand something.
Then I found the howtoforge.com site. One of its operators - who goes by "Falko" - writes the best Howto's I have ever run across. Not every Howto on the site is outstanding, but everyone of his that I have used is truly a work of art. I have already paid my subscription to his site. It is a lot less than what I pay Red Hat and much more effective. I am even learning to love the command line!
Zack said:Good one! Very rare to find a well written howto.
Posted this at http://www.howtohut.com/howto_write_a_howto
Lv said:well,can you tell me how to add "Add to: del.cio.us | digg | furl | blinklist | netvouz" at blosspot,thanks,i'back soon.
nongeek said:tomd:
You're right. A good documentation is very important and howtos may help any project to build a good documentation.
zack, sandeep:
Thanks!
lv:
You can read about it here
André Simões said:Can I translate this post to the Portuguese (PT-BR) and publish the translation on my blog, giving all it credit to you and linking to the original post?
said:Can u review the Howtos I wrote in my blog? I wanna know how they are.
http://www.theusefulblog.com
<< Home
