Jump to content











Photo

Tutorial on writing Tutorials


  • Please log in to reply
11 replies to this topic

#1 ispy

ispy

    Silver Member

  • Tutorial Writer
  • 618 posts
  • Location:PILGRIM

Posted 09 March 2008 - 10:06 AM

Hi All :) ,

I have done a little bit of soul searching about this topic in the respect will this be a Bit like "Telling your Grandmother how to suck egg's (Well known English saying)" E.g. But then I thought well perhaps it would be a helpful aid for tutorial writers as a quick reference guide of criteria to try & satisfy whilst writing them. Consideration was also given to the "Newbies" section, I thought I might be "jumping the Gun" in researching this but even if the vote is still "No", good tutorials are always beneficial, so please do not shoot the messenger!

I lay "no" claim to this information you may agree/disagree with the content. I have obtained this information off the www. from various web-sites I have visited but me seems to cover most the bases in a generic outline!

My appologies in the respect that this tutorial is only in english for those who wish to view the details in their native tongue please use this link to convert to your own language. (Good point Online!)
See here: http://www.google.com/translate_t

Anyway hope you like it, & more importantly it helps:

Can I first start out with some quotes that Peter (Psc) made in one of the forums & build upon this fundamental truth. (Sorry! Peter I hope you don't mind me using you in this way!)

Point is that experienced members tend to give as acquired a lot of "unspoken truths", the fact that they know about that particular topic make them think that all other people know about that and know as much..


Independent from WinBuilder, I often said that I don't feel as good teacher, because in most things I'm speaking about, I assume that my conversation partner has the same knowledge like me.


& Here it is "The Sweet 16" If my maths is right?:

Plan Ahead A good tutorial engages the reader by giving them a problem, having them create something meaningful that solves that problem, and more importantly, teaches the reader why the solution to the problem worked.

Don’t assume people have the same knowledge as you. Imagine having to write instructions on how to make a cup of tea for someone who has never used, or even seen a kettle before, ‘boil kettle, add teabag, add milk’ simply wouldn’t work. You’d have to tell them how to plug the kettle in, to fill it with water first, where the switch was to turn it on, etc.

The same principle can be applied to your tutorial, don’t just tell people, for example, to apply a Gaussian blur in photoshop – you need to tell them how to apply the blur – what drop down menu do they need to access to get to the blur options, what settings are they supposed to be using, and what layer are they applying it to? Write your tutorial as if talking to someone who has little or no previous experience of the program. (Thanks Peter, so very true).

when writing a tutorial, try digging deep into you memory, remembering how did you learn this stuff you’re teaching now others about yourself, and give some personal examples...


Clarity is important. You need people to be able to understand your instructions, if they can't, your tutorial is useless. Get a friend to check that it makes sense, and run it through a spell-checker. Be crystal clear what the tutorial is about, what are its goals, and give some directions as to what to do next, after reading your tutorial - perhaps more reading, or more practice….

Keep Instructions Simple. More than likely, your tutorial will have the user follow a series of steps in order to create something interesting. Avoid introducing big-picture explanations, commentary, etc. during this part. You will have plenty of opportunities at the end of the tutorial to elaborate on details.
Make your tutorial easily readable with all the bullets, headings, not very long paragraphs, highlight important terms.

Write casually Your readers are humans! Try to make your writing natural and more human-like. Be funny. A good tutorial is a conversation. It is not a page from a dictionary. Make it fun - people like to have fun while learning something new.

Antiscipate Problem areas When writing a tutorial and you feel that the user would be confused by a particular step, feel free to provide an explanation. A simple Note box helps inform the reader that what you are writing may not be directly relevant to the tutorial, but it may clear up any doubts the reader may have.

Know your information. Before you even think of writing a tutorial you need to know what you are teaching. This is the most important of all the steps, even a tutorial with bad grammar, no pictures, and incomplete steps will teach the reader something if you know what you are talking about. Having a good introduction is very important. It helps both you and the reader to get a feel for what the tutorial is about and what to expect.

Organize your information. A tutorial needs all the information about the subject in the correct order to help another person recreate an experience. Hopefully the reader will learn something useful from your tutorial. Write in steps - this makes it easier for people to keep track of where they are. Try to make each step as detailed as possible while still being short enough so a person can remember it without referring back to your tutorial. E.G.

Share with people every step and technique you’re using. There’s nothing more annoying than getting to the end of a tutorial, finding your image looks nowhere near as good as theirs, accompanied by a little note saying ‘I fiddled around a bit with my settings.’ You’re writing a tutorial because you want to share your knowledge. If you don’t want to share everything you have to offer, don’t write the tutorial in the first place, leave it for the people who aren’t so selfish. One of the most annoying examples is 'now jut shade the left side of her face' ... using what brush? And on what settings? 'advice' like that is useless..


Use images to enhance your explanations. Images help give a visual cue to an instruction you are providing, but they also help the reader to get a break from staring at text for a long time also!Use lots of visual aid with your tutorial: screenshots, flow-charts, comparison charts, pictures - anything that will help people to digest your tutorial quicker.

Create a great Example If you want the reader to be interested in your tutorial, try to create a great working example of what you are about to explain. The better looking your example, the more eager your reader will be to try to re-create the example based on instructions in your tutorial.

As you refine your own methods, refine your tutorial as well. Maybe someone better than you will come along, and show you another trick you can do to make your finished product look even better – if they do, update your tutorial. Share the knowledge.

Link Out - link out to other articles and tutorials for more info, or for the other versions of explaining the same things you did.

Explain to people why you are instructing them to do something. E.G. Telling someone to stick a layer on multiply will let them know that to achieve that one effect, they need to have the layer on multiply – telling them what the tools do and why you’re using them will allow them to apply the knowledge in other situations.

A good tutorial should speak the readers language If you use specific terms (and many times you’ll have to), make sure you have a glossary included with your tutorial. E.G. It’s pointless to tell me that I should be ranking better in SERPs, if I’m a complete newbie to internet marketing. If your tutorial is addressed to me, make sure it is fully readable by me. Also try to minimize the usage of abbreviations.

A Good Tutorial should leave room for Feedback - Sometimes readers would need further clarifications on an issue which you thought you covered well, but they still don’t get to the point. A good tutorials website should have comments enabled, allowing readers to express their wish to go deeper into some of the presented topics. If you write tutorials, get ready to answer all kind of questions pretty quickly (if you want to be a really good tutor).

Drawing in Traffic a further Consideration & Selling Yourself -I've heard from some of my closest website-owning friends that they started a series of tutorials to draw in traffic. Okay, granted, writing a tutorial that has keyword-rich content can draw in website traffic - it will get indexed in search engines and more people are likely to find you. What good will thousands of hits do you, though, if people see that they've been tricked and decide to never return to your site again? It happens - often.

The END

Observation: Can I point you to what I think is a good example of writing a tutorial, Amalux has written a guide in repect of Building a LiveXP CD you will find it within this section

I will just finish with this example & quotes from other observers:

Often I see people posting anatomy tutorials when they themselves do not have a good grasp of anatomy, or posting tutorials on other techniques that they have barely grasped. Or they write tutorials that assume you have exactly the same knowledge of the software as they do – or the best; a colouring tutorial that lacks any images to show you how your own image should be progressing.


With this in mind - A Good Tutorial should leave room for Feedback Is there anyone with any comments or anything I have missed, even if it is only to say something like, "Goes without saying"???

Regards & Best Wishes,

ispy :(

#2 online

online

    Silver Member

  • Advanced user
  • 767 posts

Posted 09 March 2008 - 01:15 PM

Don’t assume people have the same knowledge as you

And I would add: "Don't assume that readers are people of your native language"... :cheers:

Hi, ispy!

Really I had some difficult about reading all your post (please, look my flag... :cheers: my native language is not english...)... and finally I thought that maybe I understood the juice of your post, but also I think that Internet is a great "tool" (and BootLand forum more... :cheers: ), then if an acronym was unknown then is not too difficult to learn more about it... furthermore the room in order to discuss about Tutorials or other stuffs seems to me that it is already available... :)


Btw: really I think that everything can be interesting about personal preferences will find in Internet and in (this great) forum(s) a real and concrete opportunity... and also I think that a newbie can "grow", if he has the will, very quickly... if he really wants... :cheers:


Btw2: in my opinion psc's teaching (that you have quoted) is a pleasant (and effective) teaching: he does not "offer" to you "the coconut already hulled" (this is my native language expression... :(), but he shows to you the way in order to reach a result...
And personally I totally agree that kind of way http://www.boot-land...?...ost&p=20921... :cheers:

#3 Nuno Brito

Nuno Brito

    Platinum Member

  • .script developer
  • 10549 posts
  • Location:boot.wim
  • Interests:I'm just a quiet simple person with a very quiet simple life living one day at a time..
  •  
    European Union

Posted 09 March 2008 - 02:56 PM

Good topic, worth re-reading when creating my next tutorials! :)

#4 ispy

ispy

    Silver Member

  • Tutorial Writer
  • 618 posts
  • Location:PILGRIM

Posted 09 March 2008 - 03:20 PM

Hi Online, :) ,

Firstly, great to meet you & you are "absolutely right"

And I would add: "Don't assume that readers are people of your native language"...

In my haste & the research I have undertaken "the language barrier" was not in the forefront of my mind, "My Appologies!"

The only thing I can suggest, as a work around is tip that "Nuno Brito" gave me within another forum topic was this statement "Google is your Friend" & he guided me to a translator as the text I was trying to read was in Russian which was complete gobbledegook to me.

See here: http://www.google.com/translate_t

Otherwise, I would need to translate the above into every language which is way beyond my capabilities, however your remark is duly noted, Again My appologies! I will amend the above post witha link to the google translator to give it an international flavour.

In respect of acronyms I consider this a minor point, I think the author is referring to excessive usage of them e.g. like Mobile phone talk, it is a short hand way of communication but should be used economically as a teaching aid?

I have to confess I like this expression & if you don't mind I may find occasion to use it in the future, good one!

"the coconut already hulled" (this is my native language expression...


I also have to say that I also like your flag, my wife & I have had several vacations in your country we have found the people to be both warm & friendly & most of all you have got a lot better weather than us.

In respect of the "Don't give a man a fish. Teach him how to fish instead!" I agree in principle with this statement within a given set circumstances or set within the right context. Viewed from a moral stand point & this is my own personal view.

I would "Not" like to think that I could idly stand by with a bag full of fish slung over my shoulder watching a man struggling, when I could quite clearly see He needed my help! In this circumstance I would approach the man, reach into my bag, give him a fish then proceed to show him some fishing tips especially if I was an expert fisherman & he wasn't.

The only reason I am saying this for example is that many will use a statement to abstain from helping first e.g. Many people will take a statement out of the Bible say & surround their lifes philosophy around a single section of text. They will quote you chapter & verse without reading what goes before & what goes after i.e. "The context to me is very important". I am not trying to lecture you merely trying to explain a moral standpoint I have, well at least I hope I have!

So my friend, if you ever need a fish, & I have a bag full of fish, I will gladly give one to you & also give you fishing instructions to help you catch the next one, if of course need ever arises.

Also Thanks Nuno for your comments they are encouraging!

Mucho Regards,

ispy :(

#5 pscEx

pscEx

    Platinum Member

  • Team Reboot
  • 12707 posts
  • Location:Korschenbroich, Germany
  • Interests:What somebody else cannot do.
  •  
    European Union

Posted 09 March 2008 - 03:54 PM

Firstly, great to meet you & you are "absolutely right"

In my haste & the research I have undertaken "the language barrier" was not in the forefront of my mind, "My Appologies!"

The only thing I can suggest, as a work around is tip that "Nuno Brito" gave me within another forum topic was this statement "Google is your Friend" & he guided me to a translator as the text I was trying to read was in Russian which was complete gobbledegook to me.

I think Online has the same concerns like me.

The goal is not to have a translation (in my case into German).
The goal is to be able to understand the English posts without using (bad) computer translation.

To help us one should:
  • avoid slang
  • always use the most common word having the desired sence
  • try to use short sentences
Peter

#6 online

online

    Silver Member

  • Advanced user
  • 767 posts

Posted 09 March 2008 - 06:19 PM

Hi, ispy!

First of all let me kindly say: no apologies, please... here we only compare our notes (simple opinions)... :)

I have to confess I like this expression & if you don't mind I may find occasion to use it in the future, good one!

I have roughly translated in English that expression from my native dialect... :( and of course you can use it when you want: I'm glad that you like it!

About other considerations I think that "nothing" (except maybe technical notes) would must be taken litterally: about the "fish and fishing story" it's the same... :cheers: and if this was a philosophical thread, I would like to say (much) more... :cheers:

Probably the lenght and/or difficulties to well-understand some posts are my limit, but I think that if some posts was shorter and simpler to read probably they would be more followed (always in my opinion)... :cheers:

#7 online

online

    Silver Member

  • Advanced user
  • 767 posts

Posted 09 March 2008 - 06:23 PM

I think Online has the same concerns like me.

The goal is not to have a translation (in my case into German).
The goal is to be able to understand the English posts without using (bad) computer translation.

To help us one should:

  • avoid slang
  • always use the most common word having the desired sence
  • try to use short sentences
Peter

I couldn't agree more! :)

#8 ispy

ispy

    Silver Member

  • Tutorial Writer
  • 618 posts
  • Location:PILGRIM

Posted 09 March 2008 - 11:50 PM

Hi Online, Peter, :(

Thanks for your replies, I think the problem lies primarily in the language barrier, I'm not sure whether it is the content of the tutorial that is giving you both problems or is it the length, structure & composition.

This tutorial is basically constructed & assembled from various sources on the net, in a sense I didn't write it I compiled it. It has been compiled from several english speaking authors. All I have simply done is carried out the research, glued together what I thought was the best bits from various web pages. I added the front end & added minor bits to the latter end.

I also understand about the Fish story, I was not relating to the story in a literal sense either, merely trying to offer another viewpoint from a moral perspective (my own personal view). However I respect others philosophical points of view but I don't always share or agree with them! Can I leave with this, "I agree with the fish line as a very general rule" but there are situations when the recepient would not appreciate that statement, or putting it another way, Lets agree to disagree & please leave it at that.

From the stance of condensing the tutorial The Bold headings to each paragraph may be sufficient for the majority of people the rest of the text in the paragraph is for explanation of the headings.

Can I ask a favour, & if you have the time, could you put the above tutorial through the translator & see if it makes any better sense, I would be interested to know? Also could you indicate the parts that are interpreted as slang & I will endevour to change those parts as I would like it to reach a wider audience or at least try!?

I'm afraid gentlemen you have the advantage over me in the sense that I can only speak english with a very small amount of Welsh as I come from Wales so in that sense my flag is incorrect but it is a good flag none the less.

Mucho Regards,

ispy :)

#9 amalux

amalux

    Platinum Member

  • Tutorial Writer
  • 2813 posts
  •  
    United States

Posted 10 March 2008 - 05:24 AM

Hi ispy!

Thanks buddy, I'm taking notes, good stuff! (please don't delete this one :) )

:(

#10 online

online

    Silver Member

  • Advanced user
  • 767 posts

Posted 10 March 2008 - 07:45 AM

Can I ask a favour, & if you have the time, could you put the above tutorial through the translator & see if it makes any more sense, I would be interested to know?

Hi, ispy!
Just as a funny anecdote and/or as a funny instance I will shortly report my little experience of yesterday... I was on my VistaPE and I was replying in this thread: when I read your "if you don't mind" (that only after I knew it means about my possible nuisance) I did not know what it meant, and I Googled it...
Now, if I had not a great dictionary from English to Italian (Oxford-Paravia, on my HD... but useful for one word at time), then I never would have understood your "if you don't mind", in fact Google translate it in italian something like "if you don't lie"... :)
Then I did not believe in Google and I had rebooted my machine under Windows in order to translate it through my Oxford dictionary... sure, this can occur always, but it is a funny example... then: more words, more risks! :cheers:

Btw: some joking apart, and just for my clarity and for your "serenity", I did not say your post is a "bad" post... I said (continuing your "Don’t assume people have the same knowledge as you"): "Don't assume that readers are people of your native language"... nothing more, nothing less... :(

#11 ispy

ispy

    Silver Member

  • Tutorial Writer
  • 618 posts
  • Location:PILGRIM

Posted 10 March 2008 - 08:00 AM

Hi amalux :) ,

As requested, I will not delete this post, Many thanks, I hope many people find this tutorial uselful, including myself sometime in the future, it just needs tweaking a little, I forsee.

Mucho Regards

ispy :(

#12 ispy

ispy

    Silver Member

  • Tutorial Writer
  • 618 posts
  • Location:PILGRIM

Posted 10 March 2008 - 06:34 PM

Hi Online :) ,

Thanks for posting back, it is appreciated & good comments all round!

Regards,

ispy :(




0 user(s) are reading this topic

0 members, 0 guests, 0 anonymous users