amelierosalyn.com

Skip navigation

9 posts from 2008

Why I hate your tutorial: Useless Tutorials part 2

Tutorials. Everyone has them (ok, so not everyone. But a lot of people - even I had some... and for far too long, I might add). They bulk out the content of the average site and which makes the site look more important and useful and the site owner feels better about themselves, knowing they're helping people out.

The point of a tutorial is that it should help people out. It should take them through, step by step, instructions on how to perform a particular task which would otherwise be demanding and/or difficult. It should be clear, to the point, and easy to follow.

Let's take Jane Jones, a fictional website owner who loves writing tutorials. She writes them about anything and everything; Photoshop, HTML, CSS, JavaScript, PHP, you name it. She copied wrote all the iframe and blur effect tutorials first, dontchaknow. Anyway. Jane Jones comes across a script she likes - it takes text entered in a form and stores it in a database. She hasn't written a tutorial for at least a day now and she really loves this new script she's found, so she decides she'll write a tutorial for it.

She could start by writing about how the form could be extended - adding an extra field, for example. She could also write about how you can jazz up the layout a bit, for those who don't know how to do it. But this is all far too advanced for Jane... She starts with the traditional installation tutorial. "Create a database, see my other tutorial for details," writes Jane. "Then upload all the files. That's it!". Yay, one tutorial done. Second tutorial: "How to add text. To add text, write in the box and then press ok. That's it!". Next one: "How to delete text. To delete text, click the delete button. You're done!"

Let's say I'm using the script Jane has written the tutorial about. What have I learned here? I already know how to add text - it's fairly obvious, and anyone with half a brain would have guessed that you enter text in the box and then click the button. Even the most dim-witted person in the world would be able to guess that clicking 'delete' would, oh, I don't know, delete text?

So I ask you this: as a site owner, why are you writing that tutorial? Because you feel like sharing knowledge? Because you think that explaining the way you did something would help others? Or is it because you want more content? Or even because your hits are low and you want more on your site to keep them entertained?

Does your tutorial point out the obvious? Is it actually teaching anything? Writing a tutorial of the type Jane wrote above will insult the intelligence of your visitors. People will read it and wonder why you bothered writing it.

(And no, before anybody asks, this is not directed at anyone or any tutorial in particular. I see these sorts of tutorials all over the place and they do my head in.)

PHPAskIt is insecure!1!1!zomg!11

I came across a couple of websites discouraging the use of PHPAskIt because it uses a database and therefore absolutely must be insecure.

One such example states:

PHPAskIt isn't completely secure, either. It uses a database so I woulda thought that was more INsecure than the flat file of Waks Ask & Answer script.

Another says:

PHPAskit is just as insecure [as Wak's Ask&Answer] only people think it's secure because it's not flat file.

And so on, and so forth.

For the record, there is no difference in security in using one method or another, as long as they are both done properly. Wak's Ask&Answer and CuteNews (flat file scripts) aren't. PHPFanBase and SimpleDir (MySQL scripts) aren't either. Jem's Bella~ series and FlatPress however, are flat file scripts and they are fine. Similarly, WordPress and PHPAskIt are MySQL scripts and they are absolutely fine.

Yes, it's true that hackers discover more and more vulnerabilities in scripts and programming languages all the time, so those scripts may not always be secure in their current versions so it is very important to keep your scripts up to date. But to say a script is insecure because of the method of storage that they use is stupid and shows complete ignorance. If you are going to say a script is insecure, don't just back it up with "well I looked it up online and it said it was insecure". People seem to like publishing fake reports of insecurities (probably where all this is coming from, actually... PHPAskIt had a nice security hoax published about it - and in case you're still living in the dark ages it was wrong) so "looking it up online" isn't always the answer.

If in doubt, ask someone who knows what they're talking about. :)

You don't need to ConvertToPHP just to use includes

I have seen countless threads on the various forums from people who are asking for help because their member lists don't show in whatever popular fanlisting script they're currently using. When asked for their code, 9 times out of 10 it looks like this:

<?php
include('header.inc');
if(!$_SERVER['QUERY_STRING']) { ?>

Here are all my members!!!!
[Insert member list code here]

<? } include('footer.inc'); ?>

Can you spot what's wrong with that?

If you can't, here's the answer. Most fanlisting scripts use the query string (that's the bit that comes after a ? in a URL, such as country=USA in a URL like members.php?country=USA) to display members from different countries. The code there includes a line which says if (!$_SERVER['QUERY_STRING']) { which means "if there is no query string, do the following..." ... and the person has stuck their member code in the "do the following" bit (signified by the { and }). The members list WILL fail here, because it relies on the query string. If you tell the members to only show when there is no query string, it will break when you attempt to go to a country.

Now the reason this is happening so often is because it seems that people think "ooh I need a PHP page... How do I do that? Ah, NL-ConvertToPHP." This is wrong, people! All you need to have a "PHP page" is to give it a .php extension. If you want headers and footers (which NL-Convert uses as well), there are millions of tutorials on how to do this online. Don't assume that just because that script is called "ConvertToPHP" it is the be-all and end-all of how to make PHP pages.

Oh yeah, and I have internet again. Just in case anyone was wondering.

Older Entries