Writting Tutorials For Your Website An Overview To Layout And Content

I was recently asked about suggestions for tutorial layouts.

 

vujsa sorry to cut in here, but do you have any advice for tutorial layout (and like what is good to build for creation)?

 

My site has somewhat a simple and good enough file layout, just basic tables with minimal information, description and screenshot, but I have never gotten the tutorial aspect off the ground because it's rather annoying to write for and have it displayed nicely.

I'll attempt to give some insite and guidence in this area but not sure that I am the right person for the job. Many people find my tutorials easy to understand and as a result I get questions like this one from time to time.

 

---

[/hr]

When writting a tutorial, it is important to know what it is that you want to talk about. That is, choose a subject and stick to it. Don't stray off the path or leave important information out. Having a detailed knowledge of the subject is important but not always required. As long as you have a working knowledge of the subject and know how to get detailed information about it, you should be okay. The most important thing to remember is to not leave anything out just because you think that your reader should already know it. You don't have to explain the simple stuff usually but you need to point them to a resource where they can get that information if they need it.

 

Knowing who you are talking to is also important. If you are talking to a bunch of programers, you freely discuss new ideas without a full overview of the code behind it.

 

I like to make a few notes before I begin writing to help keep me on topic and to be sure that I don't leave something out. Then I begin writing. I usually write freestyle and just let the words flow out! This isn't an approach everyone can take but it works for me. Whenever you have a chance to provide an example, you should!

 

Including examples in your tutorials is absolutely essential to the success of your article. Any examples used must work and must have some type of focus placed on it. If you are talking about programing, you need to include a working example script and that section of code should be different from the rest of the text on your page. For this forum, we use the CODE tag that offeres the same result. The readers eye will automatically recognize that this section is different. Do not include an example without explaining it fully. It may be that the example is actually explaining the text around it but in either case, there must be an example to text connection. The reason for this is that many people only read what they think is important to them. So they see the example, think it is what they need then they read the text above and below it to understand what they are seeing. It is also a important for scripting that you provide the result with the code. Your reader shouldn't have to run the script to see what it will do. Show them the code then show them the output. Many programers won't even have to read the text if the input and the output are displayed together!

 

It is not good enough to place a bunch of screenshots on your page and call it a signature creation tutorial if you didn't bother to explain each of the images in detail. This is because a picture is worth a thousand words but your reader might only read the wrong 800 words of the picture. Even if they understand exactly what you are trying to show them, their sofware might be a different version or a completely different title altogether! If a signature creation tutorial is written well enough for photoshop, a person using GIMP should also be able to accomplish the same thing.

 

Flash based tutorials are great to look at but many time lack the ability to keep a users attention. For most Flash based tutorials, the user cannot fast forward to the part they are interested it and they can't control the speed at which the information is provided so they can't do while they learn. They have to watch th whole thing and remember all of the information then try it themselves just to have to watch the video 10 more times. If you do Flash based tutorials, that is great but you have to have a written version as well.

 

---

[/hr]

When it comes to layout for a tutorial on a forum, you are pretty limited in your choices. You can't caption your images and code well enough and everything is in a vertical format. On your own website, you have the option to place a note or caption above, below, or beside any examples you might have. You can also place those examples above, below, or next to the text that it is relevant to. This allows you to present examples without interupting the flow of text. This is the way that books are written. Again, be sure that your example is as close to section of related text as possible. This way your readercan quickly find the information they need.

 

Be sure to break your tutorial into sections. If your screen is filled with endless text from top to bottom, nobody will read any of it. We want our information given to use more directly. Find the example on the page that is what I need and read the text that explains it! Using a horizontal rule will give the reader a reference point while scanning the text. Their answer is either above or below that line!

 

---

[/hr]

Now for the look of your tutorials, it should stand out from your regular website pages. To avoid the black and white ugliness that a lot of text will create, I suggest that you use a tinted background color and a charcoal text color. A very dark but not black font will dull the contrast from normal black and white. Also, using a very light but not white background will make the page less intense and make the text easier to read. Using a rather plain background image is fine as long as the text is easy to read on every color of the background. Also, a busy background will make focusing on the text difficult and as a result hard to read.

 

I highly believe in linking as much as possible. If you come to a word that is best defined on a different website, link to the page it is defined on. Words that you can define yourself should use <span title="My definition">word</span>, <span title="My definition" style="text-decoration: underline;">word</span>, or some type of info bubble script that will pop up when the cursor hovers over the text! Basically, your tutorial is meant to help others with something that you have knowledge in. It doesn't matter if the person ends up somewhere else as long as you have helped them. So, if there is information that can help your reader, link to it!

 

Well, I think that this should get you started on writing tutorials on your website. Providing this type of information to your users will undoubtedly attract more visitors to your website and when you show someone the answer even if it isn't on your website, they will remember and return. Truly original and useful content will also catch the eye of the search engines which will again increase your traffic and page rank both resulting in an increase in ad generated income. It is also a good idea to seek the assistance of other when adding tutorials to your website.

 

Hope This Helps.

 

vujsa

Brilliant vujsa, I'd just like to add my two-bits.Before you start thinking of writing a tutorial, check out your visitors. I don't mean stare at their rear-ends, I mean track their behaviour on your site. Why write an endless tutorial when most of your visitors only come to your site to see the latest comic cartoon, catch up on a bit of gossip or just download your latest offering? The more information you have behind the average visitor, the better.There are plenty of tools out their to help you track the your visitors through your site.Additionally, to paraphrase Problogger, it's not the writing of your content, it's the editting. There are few writers out there capable of coming up with a captivating article first-time round. Make sure you spend at least an hour checking through your article, making adjustments and even get the opinion of someone else if you can.Anyway, I don't want to w.h.ore this topic anymore.Again, excellent advice on writing tutorials.P.S. The point about the design of tutorial, specifically the dark text on light background - you can use pure white and black as long as their is stark contrast in that area to the surrounding areas and that the content area in question is in good proportion to the rest of the layout.

Edited April 5, 2007 by mik (see edit history)

Wow, I must say this is a very good tutorial on writing tutorials....I really liked some of the things about the font, because I usually use the standard black font on a white background, so maybe i'll look into changing that around on my website...Also, I have to say that the topic point is very important....the number of times I see tutorials written that don't seem to have a very clear, or important topic is very great. I mean, don't write a tutorial just to try and draw visitors to your site, write it because you have something specific you are trying to teach people.Would anybody happen to have any good scripts that'll place a popup window on text with a definition? Because that is a very good idea, and I have a feeling that it might make my tutorials a little more compact and easier to follow...

Very nice, I'm sure it will be helpful for people who write tutorials. Oh, that reminds me that I need to write one for my game! I'll be sure to use this for some help on what to do and how it should be. Thanks alot for your tut on tuts!

great info...can you add more so that I could extend my knowledge in designing a website