Tutorial: What to avoid while writing a tutorial
Results 1 to 10 of 25

Thread: Tutorial: What to avoid while writing a tutorial

Hybrid View

  1. #1
    AO Ancient: Team Leader
    Join Date
    Oct 2002
    Posts
    5,197

    Tutorial: What to avoid while writing a tutorial

    Introduction

    The Security Tutorials Forum of AO is an important place. It's the place where people come to find out exactly how to do something. While that may seem like a simple thing it isn't. What you take for granted or manage to get working by pure dumb luck may be an absolute roadblock for someone else. So tutorials need to be detailed and exact. Having read lots of the tutorials here, and having _actually_ read the "sticky" at the top of the forum, I am finding the forum being a little "polluted". It's polluted with little things that irk me and I'm sure irk others. So, partially as a reminder of what was said in the "sticky" and also as some things that may not have been made clear in it I am writing this

    Things to avoid when writing a Security Tutorial

    1. It doesn't take a rocket scientist to look through the forum and notice that people get lots of nice little "greenies" for writing tutorials. This is not an invitation for people who have less "greenies" or even a pile of "negs" to come and even out their "piles" by presenting something less than informative. If you have an AP issue, please, take it to General Chit Chat and see if you can improve your standing there. The information presented here should be "of use". The more rubbish that appears here makes it harder to search for others.... Respect them.

    2. Starting your "tutorial" by saying "this is for noobs" does one of two things. Either, it implies that you do not really know your subject, or, you think you are some kind of hot-shot. In the first case, (which seems to be the norm), you are pre-stating that the information that follows is of little use to anyone or is already easily discovered elsewhere. In the second case, the subject matter of your "tutorial" had better be detailed, informative and of use, (How to tracert an IP is hardly something a truly 1337 h@x0r should be writing about).

    3. Don't apologize for your spelling or grammar. Typos are one thing from people who know their spelling and grammar is "up to scratch". The forum has a spell checker. If you know you are a bad speller then isn't the time you spent working on your tutorial worth the extra few seconds required to use it? If grammar is your issue you all have access to something like Word or Wordperfect somewhere..... Again, if you spent time writing the tutorial isn't it worth the small amount of time to check it?

    4. Don't start a tutorial and after one screen of text write "more to come" or "to be continued". It implies that you are in a hurry. Tutorials written in a hurry are usually inaccurate or incomplete and, as such, they are of little use.

    5. Please be complete. If you are going to start a tutorial it's simply not enough to cover one tiny little corner of the issue because by doing that you leave out the logical extensions of that issue. By leaving out the logical extensions you leave the reader with a sense that the issue is closed when, in fact, it isn't. Then your tutorial is incomplete and reduces it's use to the intended audience. If the subject is too broad to be covered in a reasonable amount of time - at least spend the time to alert the reader that other issues are connected, delineate them, and warn that they should be researched by the reader.

    6. Read what you wrote, carefully. Read it once for yourself and then re-read it as "someone else". Throw away your concept of what you wrote and read every word like it was the first time you have ever seen it.... Then correct it, fix it, re-read it and finally post it. You'll come across as a more thoughtful, thorough and useful tutorial writer if you do.

    Here ends this brief tutorial.... There is nothing more to come, it's not just for the script kiddies, my typo's be damned and my grammar is just fine.....
    Don\'t SYN us.... We\'ll SYN you.....
    \"A nation that draws too broad a difference between its scholars and its warriors will have its thinking done by cowards, and its fighting done by fools.\" - Thucydides

  2. #2
    Junior Member
    Join Date
    Nov 2006
    Posts
    1
    I think this article is quite useful and helpful for those who are to post their tutorials. There are really things we need to pay special attention to, not only to show our respect to the website administrators as well as the other members and guests, but also to show our own values, spirits, or, attitudes. We need to be careful, concerned about things that we're doing.
    By the way, I am a stranger to AO. Hopefully I can learn something and enjoy it.

  3. #3
    Junior Member
    Join Date
    Feb 2010
    Posts
    3
    Thanks for the info.

  4. #4
    Junior Member
    Join Date
    Dec 2010
    Posts
    3
    4. Don't start a tutorial and after one screen of text write "more to come" or "to be continued". It implies that you are in a hurry. Tutorials written in a hurry are usually inaccurate or incomplete and, as such, they are of little use.
    - Best way to put it... if you rush while writing a tutorial, it would just end up looking like a rough draft.

  5. #5
    AO BOFH: Luser Abuser BModeratorFH gore's Avatar
    Join Date
    Oct 2002
    Location
    Michigan
    Posts
    7,177
    It's good to see people reading the FAQs along with the AO rules, but apparently you missed the one about replying to super old threads. The other guy did too.... This was done in 2004 and the fish who did it no longer comes here anyway.

    I'm not busting your balls or anything like that, but this is a pretty old post.
    Kill the lights, let the candles burn behind the pumpkins’ mischievous grins, and let the skeletons dance. For one thing is certain, The Misfits have returned and once again everyday is Halloween.The Misfits FreeBSD
    Cannibal Holocaust
    SuSE Linux
    Slackware Linux

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •