tutorial write-up format?

I'm putting together a tutorial and i've a habit of being terribly verbose (anal if you will) I'm curious to know what the community thinks would be a decent format for a tutorial, i.e. what to include that would make it easily readible, where at the same time highly informative and able to be recreated.

Personally I really hate it when i can't recreate things, i.e. lets say there's some really old school bug that's really interesting, but long since patched. If there was a writeup that told all the circumstances surrounding using the exploit etc, where it could be easily recreated in a lab, ther'd be a lot less newbies, I think at least.

I'll have an actual example out once i finish up my tutorial, but what are your thoughts?..what would be a decent format?

I dont think people really mind what "format" it is in. I think the key is to just keep it organized. Headings and indents are key.

Good luck!

Quote:

---

I'm putting together a tutorial and i've a habit of being terribly verbose (anal if you will) I'm curious to know what the community thinks would be a decent format for a tutorial, i.e. what to include that would make it easily readible, where at the same time highly informative and able to be recreated. Personally I really hate it when i can't recreate things, i.e. lets say there's some really old school bug that's really interesting, but long since patched. If there was a writeup that told all the circumstances surrounding using the exploit etc, where it could be easily recreated in a lab, ther'd be a lot less newbies, I think at least. I'll have an actual example out once i finish up my tutorial, but what are your thoughts?..what would be a decent format?

---

Try paragraphs? :D

lol nihil

Once it's easy to follow and descriptive - that's all you need IMO.

Big suggestion: Dont go on tangents. That is, if you start talking about something stick all the way through that subject. Even if you hit another topic that may require explaining, hold out till after you explain the current one.

I have found many many tutorials that go from one thing to the next and back again, very confusing.

Also if your tutorial is going to be long make sure to organize it before putting it out for everyone to read. Hit topics in order so that there is a 'flow' to them.

Lastly, tutorials are much easier and enjoyable to read if there is a little humor in them. Long tutorials can be very boring depending on the topic and a little humor goes a looong way.

Good luck

Quote:

---

Originally Posted by mungyun

Big suggestion: Dont go on tangents. That is, if you start talking about something stick all the way through that subject. Even if you hit another topic that may require explaining, hold out till after you explain the current one...Lastly, tutorials are much easier and enjoyable to read if there is a little humor in them. Long tutorials can be very boring depending on the topic and a little humor goes a looong way.

---

I'll have to agree with mungyun here. Staying on topic is a foundation for a solid tutorial.
Don't forget to read this:
http://antionline.com/showthread.php?t=254750
There are lots of things I wouldn't have thought of myself, if I were to write a tutorial, that are contained in this thread. Many of these things go hand in hand with all writing, so think of it like writing a paper in school. For example, it is stated in the topic i listed above, don't write your paper in one day. Give your mind some time to get off the subject, then you will view it in a new light.

and btw, I rely on smart people writing good tutorials for most of my learning, so the pressure is on you! :D

As long as it has animated stick figure .gif's throughout the tutorial, then it carn't be that bad.. ;)

But seriously though if you choose a topic for a tutorial then stick to that topic and if you hit something that talks about some other topic then maybe make another tutorial touching on the other topic...?

also simple pictures add some wow to a tutorial, and also help to understand the tutorial.

just a few ideas thrown into the mix. :)

Deth by Powerpoint peut etre mes amis?

I have a brilliant sequence of a ground attacks by 4 F-16s

Then there is this stuff I got from a mate........... I guess it was a bad day for the Taliban................ we have my mate (2 recon) and a couple of guys off the USS America or whatever........ they are F-14 Tomcats................ OMFG The taliban armour flying through the air?

Oh well?:D

lol, wow @nihil, taking everything into account i think its going to be a job. thanks for the input.

Hi n00bius

On a more serious note, you need to consider how you want to deliver the tutorial? For example straight text, powerpoint presentation or whatever. My point is that different media require different styles.;)

I would recommend that you develop an indexing system for plain text presentations, something like:

1.1.1
1.1.2
1.1.3
1.2.1

and so on. then if you need to cover a different but related topic, you can add it later and just refer to it. That will help prevent your tutorial getting too complex.