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