Writing Good Tutorials An introduction

[iGuest 3]

Before posting a tutorial, please make sure that it meets a few basic requirements:

The spelling is as accurate as possible.

The language used is as understandible as possible.

As few slang acronyms as possible are used - eg. avoid things like 'IMO', 'LOL', 'FYI', 'BTW', etc.

Absolutely NO 'short-hand' is used - eg. 'u'='you', 'r'='are', '2'='to'/'too', 'c'='see', etc.

It is in English. It's not everyone's first language, but I would assume that most people here can speak it - and it's the only audible human language that I know.

It isn't copied from somewhere else. This means copying and editing to make it look like yours, or just directly copy-and-pasting it from another site (or anywhere else) - no forms of plagiarism will be tolerated at Xisto, for ethical, legal, and quality reasons.

It was originally written by you. Make sure all quotes/other excerpts are rightfully referenced to the original author/piece of work.

It is too something real and relevent. We don't want a step-by-step guide to collecting rocks from the surface of Mars.

It is of relative quality, that someone might actually find useful.

Stick to these basic guidelines - plus any reasonable additions you can come up with - and you should be on the way to writing a great tutorial.

[Eric Straven 0]

Another word of advice:

If you can't come up with a tutorial by yourself, read a tutorial on the internet and try to interpret it in your own words from what you understand. That way your writing won't be considered "copied". Stay 'clean' . No need to plagiarise, the webhosting is worth the posts.

[iGuest 3]

I once wrote a tutorial like this.Except mine was:Writing a tutorial: by SoLo1. Include as many pictures as possible so that the reader doesn't get confused.2. Make sure what you are saying makes ssence. Not only to you but to the readers. It is a good idea to let someone check your tutorial before posting it.3. Be original.4. Your final product should only show what you have told them how to do in the tutorial.5. Order your steps, like what im doing in this.Hope you all follow this, it will make your tutorials a lot better and easier to follow. Yours is better.Mind if I use some of your stuff in mine? <--- asking permission.

[Killer008r 0]

Using FYI and BTW, slang like that works pretty good in alot of books, I meen look at All the dummies books, they ALL have slang LOTS of slang like that.

[vizskywalker 0]

It is in English. It's not everyone's first language, but I would assume that most people here can speak it - and it's the only audible human language that I know.

It is imperitive that all tutorials be in English. Even though it may not be their first language, everyone here should no English. The Terms of Service and the Introduction require that all posts on this forum be in English.

 

~Viz

[twitch 0]

Well, what you just mentioned was a list of common sense factors. I do them automatically without thinking.

 

But here's my piece.

Make sure that every step is outlined in detail and explain the relevance. Connecting to your reader helps them to get more involved and feel as though they are making it, not just doing what you did.

If you come to a point that involves using a skill acquired previously in your tutorial, direct them to re-use it instead of repeating yourself. They can only gain true experience if they have to do things without being 100% spoon fed.

When using screenshots, make sure that it relates to the previous paragraph or the next one. It is no good having a screenshot of your favourite actress ona tutorial about connecting to a wireless network.

Also, screenshots shouldn't be HUGE, they should be able to fit into the window. In my first couple of tutorials, I used full-sized screenshots to show what was happening. It ate away at my BandWidth and was a stupid thing to do anyway. I tend to take a screenshot, edit out the taskbar, then re-scale the picture so that it is 510x368 pixels, then save it as a JPG.

I also like to put down why we do things the way we do it. Especially on web-design/development tutorials. It helps the reader understand things on different levels, therefore helping them in future projects.

--mik

[Xarex 1]

Some more advice for writing tutorials: A professor of mine had advised me during a presentation I was giving: "A child should understand what you are saying."In other words, simple basic English getting your point across that everyone can understand.Writing things down in easy-to-follow steps is good practice.And ensure that you don't skip something in your steps.If you are in doubt about something that someone might understand, then assume that the person will not understand what you are trying to say.If you think someone might be confused about a particular step or there might be additional details present that could confuse the person, than make sure you explain everything -- what a person should expect to see, what to do, etc.Use correct punctuation and attempt to write professionally! And especially, check your spelling. Most browsers are equipped with spellcheckers and your text will be highlighted if you spell something wrong. If you are in doubt, copy and paste it into some kind of Word or spell checker. And it's also good practice to read your tutorial over after you've finished it -- to check for mistakes and to ensure that it is fully comprehensible.