Tutorial: How to Write a Tutorial

Discussion in 'Gimp Tips & Tutorials' started by tripwire45, Jul 31, 2008.

  1. tripwire45

    tripwire45 Member

    Joined:
    Jun 30, 2008
    Messages:
    365
    Likes Received:
    0
    Trophy Points:
    16
    Occupation:
    Technical Writer, Author, and Editor
    Location:
    Boise, Idaho, USA
    Home page:
    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 GIMP GNU Image Manipulation Program. 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 instructions on downloading and installing GIMP, 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.
  2. Ajit

    Ajit Active Member

    Joined:
    Mar 29, 2008
    Messages:
    3,535
    Likes Received:
    0
    Trophy Points:
    36
    Occupation:
    Student
    Location:
    Texas
    Home page:
    Wow, you can right. :)

    I will definitely read sometime ^_^
  3. CitrusFruit

    CitrusFruit Member

    Joined:
    Jun 14, 2008
    Messages:
    180
    Likes Received:
    0
    Trophy Points:
    16
    Occupation:
    Nun!
    Location:
    B-more
    Read it all...SIMPLY AMAZING!!!!!
  4. Siddharth

    Siddharth Active Member

    Joined:
    Nov 27, 2007
    Messages:
    1,829
    Likes Received:
    0
    Trophy Points:
    36
    Location:
    India
    Home page:
    nice tutorial's tutorial :p
  5. lamaz1928

    lamaz1928 Active Member

    Joined:
    Dec 9, 2007
    Messages:
    2,205
    Likes Received:
    0
    Trophy Points:
    36
    Occupation:
    School.....*sigh*
    Location:
    Tennessee
    Home page:
    wow. you wrote all that? its like perfectly written....great work!!!!!!!!
  6. tripwire45

    tripwire45 Member

    Joined:
    Jun 30, 2008
    Messages:
    365
    Likes Received:
    0
    Trophy Points:
    16
    Occupation:
    Technical Writer, Author, and Editor
    Location:
    Boise, Idaho, USA
    Home page:
    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.
  7. tomahowk

    tomahowk Member

    Joined:
    Jul 11, 2008
    Messages:
    365
    Likes Received:
    0
    Trophy Points:
    16
    yay for this wall of text!!! very useful!!!
  8. p@nda

    p@nda Member

    Joined:
    Jul 31, 2008
    Messages:
    113
    Likes Received:
    0
    Trophy Points:
    16
    Occupation:
    Student
    Location:
    Chicago
    Home page:
    exactly
  9. DerkDigg

    DerkDigg Member

    Joined:
    May 11, 2008
    Messages:
    313
    Likes Received:
    0
    Trophy Points:
    16
    thank you, i am going to write one soon,
  10. lamaz1928

    lamaz1928 Active Member

    Joined:
    Dec 9, 2007
    Messages:
    2,205
    Likes Received:
    0
    Trophy Points:
    36
    Occupation:
    School.....*sigh*
    Location:
    Tennessee
    Home page:
    i think of it more as a Blob of Teachings :D
  11. tripwire45

    tripwire45 Member

    Joined:
    Jun 30, 2008
    Messages:
    365
    Likes Received:
    0
    Trophy Points:
    16
    Occupation:
    Technical Writer, Author, and Editor
    Location:
    Boise, Idaho, USA
    Home page:
    Only 88 hits so far...I'm crushed.

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

    sglider12 Active Member

    Joined:
    Nov 30, 2007
    Messages:
    3,610
    Likes Received:
    0
    Trophy Points:
    36
    Occupation:
    I work at Best Buy as a Digital Life Sales Associa
    Location:
    Aubrey, Texas
    Home page:
    Wow nice job. I like it. ^-^
  13. Siddharth

    Siddharth Active Member

    Joined:
    Nov 27, 2007
    Messages:
    1,829
    Likes Received:
    0
    Trophy Points:
    36
    Location:
    India
    Home page:
    :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
  14. Gimper

    Gimper Member

    Joined:
    Aug 31, 2007
    Messages:
    962
    Likes Received:
    0
    Trophy Points:
    16
    Location:
    Sydney
    Home page:
    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.
  15. tripwire45

    tripwire45 Member

    Joined:
    Jun 30, 2008
    Messages:
    365
    Likes Received:
    0
    Trophy Points:
    16
    Occupation:
    Technical Writer, Author, and Editor
    Location:
    Boise, Idaho, USA
    Home page:
    Thanks, Gimper. I'm glad the article is worthy of being a "sticky". :)
  16. starlight86

    starlight86 Member

    Joined:
    Jun 10, 2008
    Messages:
    500
    Likes Received:
    0
    Trophy Points:
    16
    Occupation:
    student
    Location:
    Malaysia
    i think this post is cool and usefull.
    8) 8)
  17. El Llama

    El Llama Active Member

    Joined:
    Nov 28, 2007
    Messages:
    1,362
    Likes Received:
    0
    Trophy Points:
    36
    Occupation:
    youtube.com/llamavlog :D
    Location:
    Franklin, Tennessee
    Home page:
    great tutorial.. im glad you took the time to explain to us some great thoughts and share some great insight on writing tutorials.. It's very rare I write one but i will keep this in mind next time i write :D thanks again!
  18. Zeratul

    Zeratul Member

    Joined:
    Aug 5, 2008
    Messages:
    447
    Likes Received:
    0
    Trophy Points:
    16
    Location:
    Lufkin Texas,
    OH m G this is AMAZING trip i think that you might have should write a book but after reading this it seems you already have hehe truly amazing im working on a tut right nowww
  19. Stanley

    Stanley Member

    Joined:
    Sep 14, 2008
    Messages:
    814
    Likes Received:
    0
    Trophy Points:
    16
    Occupation:
    Student
    Location:
    Under your bed (near the monsters)
    Home page:
    Great job =D
    One question though, since my english vocabulary is not that big, What does ''Syntax'' mean?
  20. tripwire45

    tripwire45 Member

    Joined:
    Jun 30, 2008
    Messages:
    365
    Likes Received:
    0
    Trophy Points:
    16
    Occupation:
    Technical Writer, Author, and Editor
    Location:
    Boise, Idaho, USA
    Home page:
    In a human language, syntax is the grammatical arrangement of words. In English, the syntax of the sentence:

    "Get me go cup of coffee me for, please"

    would be incorrect, even though you can probably tell when I meant to say. The sentence:

    "Go get a cup of coffee for me, please"

    would be correct syntax.

    In a computing language, syntax describes the correct construction of commands and statements.

    Hope that helps.

    -Trip

Share This Page