Support

I am sure there are many of us who do not use Filezilla. Basing an entire instruction on the assumption that Filezilla is installed is, well, just silly.

This assumption you made is just plain wrong and shows that you didn't actually read the documentation, only skimmed through it. I am describing exactly what you need to get FTP/FTPS/SFTP working.

That said, how would you explain to a non-developer who knows nada about FTP and filesystem what a filesystem path is, what an FTP path is and how these two are different – let alone how to figure out what's the FTP or SFTP (=filsystem) path to his site's root? Therefore I chose to provide some additional and perfectly redundant information based on FileZilla because, quite frankly, that's what the majority works with. I could sure as heck base the alternative instructions on Transmit which is what I am using, but I think that 99.8% of my clients would simply curse me. So, no I am definitely NOT basing the instructions on such a stupid assumption.

If you believe that I am stupid, your are welcome to contribute a passage of documentation which does not reference a commonly used tool and is so crystal clear that the non-technical average Joe can read, understand and use it without coming back for support. Please note that if someone does come for support because he didn't understand these instructions I will expect you to coach him through the steps he has to follow to figure out what the directory is. Because, you know, that's the conditions under which I have to produce documentation. Before assuming that I am an idiot please consider the fact that Akeeba Backup is up and foremost used by complete newbies.

The error message is misleading. It always directs you back to the FTP/FTPS/SFTP entry - but that is seldom the issue, at least in my case.

I agree that the error is often misleading. However there is ABSOLUTELY NO WAY to know if the user DID enter the path to his site's root or if he did a stupid thing like:
- enter the path to the directory above his site root
- enter the path to the domain's root or the root of the main site when he has a site in a directory and/or subdomain
- enter the path to another site's root
In all those cases the file is written successfully – but it's not web accessible. You are welcome to provide a patch to detect those situations on all possible server configurations so that I can finally get read of the big, yellow "Important" box in the documentation page which explains that error message and what to do when you see it.

The exact error message, if you want to be so strict, should be "The test file was uploaded but is not web accessible. You screwed up your FTP/SFTP/FTP configuration, your site's host name or you have a braindead server which uses the wrong permissions on freshly uploaded files". Yeah, that would technically be absolutely accurate but not the little bit more informative.

1) the "Host name" seems to like having the "http://www." prefix

Actually, you mean the URL to the remote site. it just requires the protocol (http:// or https://) to be entered. The documentation clearly says: "Enter the full URL to the remote site. e.g. http://www.example.com/joomla. Please, do not include a trailing slash."

2) the "URL to the remote site" does NOT like to have "http://www." OR "www.". Leave all prefixes off. This works for me. (ie example.com NOT http://www.example.com or www.example.com)

Actually, you mean the hostname. Yes, of course it shouldn't. You are a developer. You should know that the hostname to your site's FTP/FTPS/SFTP server is different than your domain name and should not include a URL. In fact, the documentation DOES read "The hostname of your FTP, FTPS or SFTP server. Please do not specify a protocol. For example, ftp.example.com is a valid host name whereas ftp://ftp.example.com IS NOT. If unsure, please ask your host. Once more, we can't possibly know how to connect to your server, it's your host that has to give you this information"

3) the "FTP/FTPS/SFTP directory to the remote site's root" should not be blank. If the FTP account already points to the site root, then enter a "/" only. If the FTP account points to a higher level directory, then include the path to the site root starting with a forward slash "/public_html" but no trailing slash.

Which is perfectly in line with the documentation and makes absolute sense. As I've written there: "This is the full FTP, FTPS or SFTP directory to your remote site's web root. This may not always be obvious and most likely should not be left blank. You can always connect to your remote site using FileZilla, navigate to the web root directory of your new host and take a look above the right-hand directory pane. You will see a path. Copy it and paste it in this box of the Site Transfer Wizard."
Now you see why I have the "stupid" FileZilla instructions? Maybe they are not so stupid after all... Just sayin'...

While these instructions are not difficult, they are not documented

No, sorry, you are absolutely wrong!!!!! The fact that you didn't read the documentation –at least not read carefully enough– doesn't mean that it's not documented. All three of your points are addressed in the documentation. Even the other point about the misleading error message is addressed in there.

Furthermore the error message often misleads to troubleshooting the FTP/FTPS/SFTP path - but that is not generally the problem (again, at least in my case).

As I said, since you are a developer you are welcome to contribute the code which will detect with absolute precision the real cause of any possible error on any possible server setup and produce accurate and not misleading error messages.

Hi Mike,

It's been a loooong day today and everything you said was already covered in the documentation. The two triggers which sent me ballistic were the initial reference to the documentation mentioning Filezilla silly and the lack of documentation. I think that between those two I just blown a fuse or two :)

Regarding your comment about Host name vs remote site; No, I did indeed mean remote site. If I include the remote site "http://www." prefix, I get the error message. For the host name, the wizard likes to have the "http://www." prefix.

This should be the other way around. I remember an old version having, indeed, the two field labels swapped in error. That would definitely explain the issue. Which version of Akeeba Backup are you talking about?

Writing the code to detect with absolute precision any error is a daunting task.

That's an understatement :D

The error proofing and validation is much harder the the actual programming logic in many cases.

In this case it's the lack of standardisation of the domain root path that makes correct error reporting infeasible. In the simplest cases it's public_html, htdocs, www, httpdocs or http_docs. But in some cases it's something like domain/www.example.com/public_html, or /, or /mnt/i/really/hate/my/life/nas/w/h/a/what/the/bloody/hell/username/domains/e/x/a/example/public/html and so on. Yes, the last one is made up but I've honestly seen paths consisting of 12 directories to get to the domain root.

The only thing I would do differently is put tool tips on the each entry block specifying the needed fomatting (ie "Do not leave Blank. Use "/" if FTP account points to root or enter path starting with a trailing slash if the joomla root is a subdirectory. Do not use a trailing slash")

You are overestimating the users' abilities to read messages with conditionals :) I've really tried such messages in the past. No go. The FileZilla method? As soon as I started using it in the documentation the support requests regarding the FTP directory plummeted. We're talking about one per month versus two per day.

Sometimes a bit of documentation with a silly approach for dummies works better than a long error message with conditionals. You can quote me on that.

OK, there is one more thing I want to implement: a directory browser. When you use the "Upload to remote FTP directory" engine in the Configuration page you get a nice "Browse" button which allows you to view a list of directories and select the one corresponding to your site's root. This is what I want to add to the STW Step 2 page. This would make this entire discussion redundant as you could just click and select the directory. No documentation reading, no error message gazing, no frustration (well, just a bit maybe).