April 23rd, 2004 11:08 PM
Tutorial: What to avoid while writing a tutorial
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
April 23rd, 2004 11:28 PM
Thank you so much Tiger. I'm sick and tired of seeing people with 10 posts under their belt Immediately start writting "security" tutorials in the most incompetent maner EVER. If you're gonna write a tutorial, at least know what you're talking about....thats important.
This should be a sticky in the main page.
April 24th, 2004 01:06 AM
Still if they have 10 posts, doesnt mean that they dont hang out much at AO and know the rules, and the newbies status under their names doesnt mean jack, they may be smarter then most of the seniors here...it just says newbies because they are new to AO.
Good Tut Tiger....
April 24th, 2004 02:06 AM
indeed thats true, but there's many of them who dont know **** about **** and they still write tuts about ****
April 24th, 2004 02:38 AM
My vote is that for it to count as a tut, it needs to be 750-1000 words...and not cut and pasted from somwehere else..
but that's just my 2 cents..
Good post Tiger, as always
April 24th, 2004 03:13 AM
Add to that a hint from a writer: DON'T WRITE YOUR TUTORIAL IN THE SUBMIT TOPIC BOX!!
Write it in at least vi, notepad, emacs, word, you know some other editor. Clean it up, make it look nice. Once your finished, let it simmer on your computer for a few DAYS!! and think about it while you work, walk around or whatever. You'll end up with a much better paper if you take your time like tigershark explained.
The tutorials are here to provide easily digestable nfo to the masses, not to get you AP's. Tigershark made that quite clear above. The masses have waited this long for your info, if it's valuable, and your not really motivated by a quick ap, they can wait another day or two.
If you have the info, there's no reason you can't treat a tutorial like a publication. That's my opinion at least. Though I've only written one (don't look at it, it's horrible). I am working on another that will be done as it should be. Notice I said 'working on' this is how most should be done, I don't plan to put it up for at least a few weeks.
April 24th, 2004 03:26 AM
Now, Im no super l33t h4x0r but...
Are you implying something towards me tiger??
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).
April 24th, 2004 03:41 AM
??? yes, that intro to a tutorial sux. besides, he's not refering just to you, he's using it as an example.
April 24th, 2004 03:46 AM
The Intro? What part of the intro? The part where I say im not responsible? At least tell me what part so I can write better next time. Besides, I felt that tutorial was needed, I have answered quit a few questions along the lines of that subject and I have only been here for a short time.
April 24th, 2004 03:52 AM
wrong post to argue about it buddy. Hope this clears it out for you:
He is not refering just to you. NO not the part about where you said you're not responsible...that doesnt clear ****. He's refering to the vague tutorials that many members write just to earn greenies.
Look bro, he's not slamming you, just an example...plz dont make it personal. I read your tutorial and it could use some touching up. I'm not going to go through the whole thing. Paragraphs are a good way of writting clean tutorials, makes them easier to read. Do a little bit more research on the topic before you write the tut.