Tips & Tutorials

Tutorial: How to Write a Tutorial

A place to share tips and tutorials. Resources for beginners and advanced users.

Tutorial: How to Write a Tutorial

Postby tripwire45 » Thu Jul 31, 2008 6:04 pm

Introduction

There actually are many fine articles on how to write tutorials on the web and particularly on those related to image editors such as Photoshop, but I thought it was time for one aimed at the beginner who wants to learn how to write a tutorial, particularly using GIMP. The writing in and of itself, is a skill set that takes time to master. It's not enough to have the desire to help others and it's not enough to know the subject you want to teach. The trick is being able to communicate to your audience in a way that will help them understand, learn, and then apply what they've learned to expand their own skill sets.

‎This is a GIMP forum, which means by definition. the tutorials here are related to creating and editing images with the . That said, I'm going to go against one of the recommendations I'll make below and deliberately not include any screen captures or graphics. For this sort of tutorial, they won't really lend much, and the idea is to be able to present ideas and concepts in a text communication format (it's assumed that most of the people who have been writing tutorials on this forum are well versed in creating graphics using GIMP).

Recently, a group of us here were "tossing around the ball" so to speak, on the subject of how to write a tutorial. Here's a list of what we came up with in no particular order:

  1. Break instructions into numbered steps.
  2. Write in complete sentences.
  3. Include plenty of graphics.
  4. Include every necessary step in the instructions.
  5. Write for your audience.
  6. Write a tutorial on a topic your audience wants to learn.

There were more suggestions actually, but they tend to overlap. Let's organize the suggestions a bit more and expand upon them.

Know your Audience

You are a GIMP guru and you want to share your knowledge with others. How do you do that? Ok, the obvious answer is that you write a tutorial to share that knowledge, but what topic do you choose? The answer depends on who you are writing for. The topics of interest for a complete newcomer to GIMP are going to be different than those of interest to a professional graphic artist or photographer who has been using GIMP for one or more years. For the sake of this tutorial, let's keep things simple and create two audiences: the beginner and the experienced user.

Writing for the beginning GIMP user means making a certain set of assumptions.

  1. The beginner may not even have GIMP installed on their computer and need to know where to go to get it and how to install it.
  2. The beginner with GIMP installed on their computer may not know anything about the GIMP interface.
  3. The beginner may not know any of the technical terms associated with GIMP or with graphic artistry or design.

With point one in mind, perhaps the first tutorial you write is one instructing your audience on how to locate, download, and install GIMP on their system. You'll need to decide if you want to include just Windows or Linux and Mac as well. If you include Linux, you'll need to decide which package manager(s) to use in your tutorial.

The official gimp.org site provides , and you may decide you can safely bypass this particular tutorial and move on to ones that provide information on how to actually use GIMP. Of course, if you previously had trouble with this issue, or know of someone who had an installation circumstance that should be further addressed, you can decide to pursue this particular topic.

Once the beginner has GIMP installed, let's assume they don't know a thing. There are two issues to consider here. First, as a GIMP guru, you have long forgotten what it was like to be a "newbie". Part of this means, you may take for granted the various steps required to perform simple tasks. If you do, in writing instructions, you may leave out steps that rarely rise to the level of conscious awareness for you because you do them out of habit. The newbie has no "habits" as such though, and will become confused if steps are "missing".

Solution: As you are writing your tutorial, go through the steps of the task yourself...slowly. Document each and every step you take. You may end up streamlining some of those steps as you edit your work, but you're less likely to bypass a step that is simple for you but critical to a newcomer.

The other issue is making the purpose of your tutorial explicit. There's no such thing as just one type of newcomer. There may be new GIMP users who do have some basic skills and others who have none. Even in the latter audience, there may be people who have very good problem solving skills and can "figure things out" better than others. Sooner or later, you may end up offending someone who thinks you're talking down to them.

Solution: Write a disclaimer statement at the beginning of the tutorial explaining that this is a beginner's tutorial and will include steps that some of the readers may already know. Your readers should be aware that you are writing for the widest possible newcomer audience, so there will naturally be some readers who will be aware of some of the information already.

The more professional audience presents a different challenge. Providing too much detail on very basic steps will just annoy them and rightly so. If you say something like, "Create a canvas with a white background at 420 x 300 px, then add a transparent layer", you don't have to tell them how to open GIMP, how to create a new canvas, how to select and background, and so on.

For this type of tutorial, the disclaimer becomes even more important. You need to explain upfront that this tutorial has been written for the reader who has at least some experience creating and editing graphics using GIMP. You can include links to beginner tutorials for those people who may have come upon the "advanced" tutorial you've written, find it interesting, but still need to learn the basic skills before proceeding in this area.

Know your Topic

This may seem like an obvious point, but I'll mention it anyway. If you are going to write a tutorial, make sure you are qualified to write it. I don't mean that you need a university degree or any other type of formal education, just make sure you know what you're talking about. That should be relatively easy if you are an experienced GIMP user and you are writing for an inexperienced audience, but what about writing for the professional? If you are well versed in GIMP but not particularly in professional photography, you may not be aware of the details that such a professional may require.

Solution: There are a couple of solutions, actually. The first is to stick with what you know, which makes a great deal of sense. Only write about topics that you are very familiar and comfortable with. The other solution is to learn what you want to write about. If you want to write for photographers but have limited skills in that area, start reading some tutorials on the subject yourself and start practicing. As you learn and start building your skill sets in that area, start documenting your experience. That documentation can end up being a series of tutorials that will helpful, first for the beginning photographer, and eventually for people more experienced. Of course, you need to have the desire and probably the talent to see this through to its conclusion. If not, stick with the first solution.

If other technologies are involved relative to your tutorial, make sure you are at least adequately versed in those skills as well. For instance, if you are writing a GIMP tutorial that involves publishing graphics on a web page, you'll need to know enough about HTML and CSS (and maybe JavaScript) to cover those areas. If you don't, you'll either need to avoid writing the topic, consult tutorials yourself, or seek assistance from someone knowledgeable in those areas (yes, you can co-write a tutorial with someone else).

Know How to Write

Teaching general writing skills is beyond the scope of this tutorial. Writing is considered an art form in its own right, so you can even ask yourself if you have sufficient talent to write tutorials. While imparting talent may not be possible, it is always possible to improve skill sets. Also, writing a tutorial doesn't require the same skill sets as writing a New York Times Best Seller. Here are some basic things to remember.

You have no idea who will be reading your work, particularly if it's posted on the Internet. Often, it's good to assume that your audience is comprised of people who read and speak English (this tutorial assumes you're writing in English, but of course, you can write in any language as long as your audience reads that language) as a second language. That means they are less likely to be familiar with abbreviations and slang. People that learn a second language, tend to learn the formal form of that language so it will help if you write using the following guidelines.

  1. Write in complete sentences.
  2. Use proper punctuation, syntax, spelling, and so on.
  3. Break long narrative information into step-by-step chunks whenever possible.
  4. Avoid using "textspeak" and other forums of abbreviation.
  5. Write in a way that describes actions (do this, click that, drag the other thing...)

That list is hardly exhaustive, but it will give you some place to start. By the way, don't depend just on a spell checker when editing your tutorial. Spell checkers are stupid and will clear words like "sale" when you meant to write "sail".

Extra points for writers who not only use an online (or hardcopy) dictionary but a thesaurus as well. While a sentence can be correct that says, "I'm going to describe for you a description of how to use GIMP to describe a curved line", it's horribly repetitive and rather painful to read. It's also incredibly common to write a sentence (more or less) like that example. When you go over your tutorial and edit it, if you need to use a word that means "describe" more than once in a sentence or paragraph, use a thesaurus to look for synonyms to that word. You can retain the technical accuracy of what you're writing and make it more interesting to read at the same time.

Style is another important consideration and it doesn't have to be a complex issue. This is also somewhat audience driven, but not to a great degree. If you are writing for an audience of college professors in physics on a highly technical topic in their realm, you are going to use very formal and very technical language and style. Thankfully, your audience shouldn't be that challenging, but you need to consider the "tone" you are offering. Try to be friendly and helpful. While you need to be somewhat "proper" in your language, you can use contractions and write to your audience as if you're talking to them. It might help if, as you write, you imagine someone sitting next to you that you're trying to teach how to use GIMP. Write the tutorial in the tone that you'd use if you were walking someone through the steps yourself at your computer.

I find it amazing in my own work that, no matter how well I think I've edited what I've written, I can put a project away, come back a few days later, and find all sorts of errors I'd missed before. The same is true of others editing my work. At the very least, don't publish a tutorial you've written right away. Let it "cook" for awhile...even a few hours. The best case scenario is to find someone you trust, and who has good writing skills, to read and edit your work (and someone who can do this gently).

Include Lots and Lots of Pictures

This actually can be overdone and when it is, it can be annoying. If you include a screen capture of literally every step, including every button that needs to be clicked, not only can your tutorial end up being very long, but it will take longer to load in web browsers, depending on the connection speed of your reader's computer.

Since we're talking about GIMP, you will end up using more graphics in your tutorial than if you were writing a HOW TO about programming in JavaScript. That said, just how many graphics and what kind, will depend on the audience. You'll tend to include more screen captures for a newcomer audience to show them how to use the GIMP tools. For both beginner and experienced audiences, you'll need to include graphics that show the different stages of the image being manipulated by GIMP. If you don't, the reader won't have a good idea if what they've accomplished by following your tutorial, actually produced the desired result. If it didn't, showing the subject graphic at each step will help the reader understand if they went wrong at some specific point.

Sizing and formatting your images is important in terms of them both being adequately viewable and not being obnoxiously large. Also, not everyone uses the same screen resolution, so test your online tutorial at different screen resolutions to see how it displays. It would also be helpful to use different web browsers, if possible. Certainly Internet Explorer and Firefox should be used for your test at a minimum and if you have access, Safari as well.

A Few Other Points

My pet peeve about a large number of GIMP tutorials on the web, is that they don't reference the version of GIMP used to write the tutorial. The interface changes between major versions and a set of instructions that says "click Script Fu in the menu", doesn't apply to the latest version available to me (GIMP 2.4.6).

Solution: Include the version number of GIMP you used to create the tutorial either at the beginning of each article or, if you maintain a tutorial site or web page, you can include a general disclaimer in some central location on the site or page.

It's said that the language of the Internet is English. I don't know how true that is, but it does seem that most web sites are written in English, even if they're written by people living in non-English speaking countries. I mentioned before about writing as if your audience was made up of people who speak English as a second language. If that audience is you, it doesn't mean you can't or shouldn't write tutorials. It does mean that you may need to take an extra step or two if you are writing your tutorials in a second language.

Solution: If at all possible, see if you can have someone who is more experienced speaking/reading that language have a look at what you've written. Even if they've never heard of GIMP, they'll be able to help as far as how understandable your instructions are to them.

The other solution is to live with imperfection. I know this flies in the face of what I said earlier, but if you have valuable information to share with an English speaking audience and you tend to put commas in the wrong place when you write in English, that's a really minor barrier in terms of offering what you know to others. Yes, people can be picky and occasionally critical, especially if they're detail oriented. While providing a well worded tutorial enhances your credibility and the credibility of the web site or discussion forum hosting your HOW TO, remember that you're not performing heart/lung transplants. If a minor syntax error creeps into a few sentences, no one dies. Even book authors make errors that escape their editors and publishers on occasion. That's why errata pages on web sites were created.

This isn't an exhaustive treatment of the topic of writing tutorials. I created it largely just to help get people started. I'm sure much more can be added and, since this is a discussion forum, anyone who wants, can add their own comments.

Have fun.
Members don't see the above ad. Register now - it's free!
tripwire45
Sr. Member
 
Posts: 365
Joined: Mon Jun 30, 2008 10:10 pm
Location: Boise, Idaho, USA

Re: Tutorial: How to Write a Tutorial

Postby Ajit » Thu Jul 31, 2008 6:19 pm

Wow, you can right. :)

I will definitely read sometime ^_^
User avatar
Ajit
Retired Staff
 
Posts: 3535
Joined: Sat Mar 29, 2008 4:33 am
Location: Texas

Re: Tutorial: How to Write a Tutorial

Postby CitrusFruit » Thu Jul 31, 2008 10:11 pm

Read it all...SIMPLY AMAZING!!!!!
CitrusFruit
Full Member
 
Posts: 180
Joined: Sat Jun 14, 2008 7:17 pm
Location: B-more

Re: Tutorial: How to Write a Tutorial

Postby Siddharth » Fri Aug 01, 2008 1:25 am

nice tutorial's tutorial :P
User avatar
Siddharth
Retired Staff
 
Posts: 1829
Joined: Tue Nov 27, 2007 11:54 am
Location: India

Re: Tutorial: How to Write a Tutorial

Postby lamaz1928 » Fri Aug 01, 2008 1:40 am

wow. you wrote all that? its like perfectly written....great work!!!!!!!!
User avatar
lamaz1928
Hero Member
 
Posts: 2205
Joined: Sun Dec 09, 2007 12:54 am
Location: Tennessee

Re: Tutorial: How to Write a Tutorial

Postby tripwire45 » Fri Aug 01, 2008 3:02 am

LOL. Thanks for the complements. :-[

I can see things I'd change now, but I won't. Hopefully, the tutorial does a few things. I hope that it, taken at face value, is helpful in teaching people the beginning steps of writing a tutorial. I also hope it acts as an example of doing the same. Finally, I hope that it acts, at least in some small way, to attract some readers here that might not otherwise surf on in.
tripwire45
Sr. Member
 
Posts: 365
Joined: Mon Jun 30, 2008 10:10 pm
Location: Boise, Idaho, USA

Re: Tutorial: How to Write a Tutorial

Postby tomahowk » Fri Aug 01, 2008 3:07 pm

yay for this wall of text!!! very useful!!!
tomahowk
Sr. Member
 
Posts: 365
Joined: Fri Jul 11, 2008 11:36 am

Re: Tutorial: How to Write a Tutorial

Postby p@nda » Fri Aug 01, 2008 3:21 pm

Siddharth wrote:nice tutorial's tutorial :P


exactly
p@nda
Full Member
 
Posts: 113
Joined: Thu Jul 31, 2008 6:38 am
Location: Chicago

Re: Tutorial: How to Write a Tutorial

Postby DerkDigg » Fri Aug 01, 2008 3:25 pm

thank you, i am going to write one soon,
DerkDigg
Sr. Member
 
Posts: 313
Joined: Sun May 11, 2008 10:17 pm

Re: Tutorial: How to Write a Tutorial

Postby lamaz1928 » Fri Aug 01, 2008 3:25 pm

tomahowk wrote:yay for this wall of text!!! very useful!!!

i think of it more as a Blob of Teachings :D
User avatar
lamaz1928
Hero Member
 
Posts: 2205
Joined: Sun Dec 09, 2007 12:54 am
Location: Tennessee

Re: Tutorial: How to Write a Tutorial

Postby tripwire45 » Fri Aug 01, 2008 5:41 pm

Only 88 hits so far...I'm crushed.

Well, not really...just hoping it would get a tad more attention. ;)
tripwire45
Sr. Member
 
Posts: 365
Joined: Mon Jun 30, 2008 10:10 pm
Location: Boise, Idaho, USA

Re: Tutorial: How to Write a Tutorial

Postby sglider12 » Sun Aug 03, 2008 12:23 am

Wow nice job. I like it. ^-^
Image
Image
PSNetwork: sglider12 <--Add Me!
User avatar
sglider12
Retired Staff
 
Posts: 3610
Joined: Fri Nov 30, 2007 2:26 am
Location: Aubrey, Texas

Re: Tutorial: How to Write a Tutorial

Postby Siddharth » Sun Aug 03, 2008 4:28 am

tripwire45 wrote:Only 88 hits so far...I'm crushed.

Well, not really...just hoping it would get a tad more attention. ;)

:D I believe only tutorial writers will see it as most of the users are looking for tutorial :D
this tutorial will be really helpful for tutorial writers :P
User avatar
Siddharth
Retired Staff
 
Posts: 1829
Joined: Tue Nov 27, 2007 11:54 am
Location: India

Re: Tutorial: How to Write a Tutorial

Postby Gimper » Sun Aug 03, 2008 6:48 am

I read through it and I must say I've learned a few pointers, thank you for taking the time and effort to write it.

I've set this to sticky for everyone to read :)

thanks again.
User avatar
Gimper
Retired Staff
 
Posts: 962
Joined: Fri Aug 31, 2007 9:03 am
Location: Sydney

Re: Tutorial: How to Write a Tutorial

Postby tripwire45 » Sun Aug 03, 2008 2:11 pm

Thanks, Gimper. I'm glad the article is worthy of being a "sticky". :)
tripwire45
Sr. Member
 
Posts: 365
Joined: Mon Jun 30, 2008 10:10 pm
Location: Boise, Idaho, USA

Next

Return to Tips & Tutorials

cron

Who is online

Users browsing this forum: No registered users and 1 guest