I don't expect anyone to read this except people involved in writing and improving the documentation for Joomla!. I would however like to hear if any fellow beginners have had any similar frustrations with Joomla! documentation (and the documentation for other "easy to learn" applications.) Also if you write manuals, guides etc for anything, you might learn something here.
First a little background/context of my story:
I want to create websites and I was in the process of evaluating various applications that can be used to accomplish this. I started researching the subject, learned about web editors, narrowed my search down, and was going to go with Kompozer. I chose Kompozer due to its supposed ease of use for beginners, and its range of features, among other things.
I was reading some general (non-program-specific) guides on creating websites. I read about templates and the fact that not all programs have the capability to apply the changes made to a template to all the webpages made from that template. I looked into it and [apparently, I'm still not sure] Kompozer doesn't have this capability. Apparently this other web editor named Quanta Plus does have that capability. So I started looking into Quanta Plus and found that its apparently not beginner friendly and its more for advanced developers [-not sure about that either].
I sought advice in a Linux forum and some helpful person suggested I try a CMS [content management system] such as Joomla! or Drupal. I didn't know CMS's could be used to create webpages. It turns out they even have (WYSIWYG) editors, plus they do all the things I want to do template-wise, -and much more! Great! But can a beginner to the world of website creation learn and use them?
After a bit of research I found that Joomla! sounds like its quite beginner friendly, including a community, intentional ease of use design, and good documentation. "Great!" I thought, "I'll learn and use Joomla!." I'm still of the opinion (and hope) that I can in fact easily learn Joomla! and use it to make the websites of my dreams. However I am quite early in my learning journey, and I'm already frustrated with how things are going.
[on a sidenote I want to say that I am still excited to be learning Joomla!. I'm glad I found it. I can't wait to get started, make some great websites, and tell the world about what a wonderful system it is. If I sound angry, know that it is more frustration than actually being angry and attemping to belittle anyone's efforts or hurt their feelings. Much of my sentiment comes from years of reading documentation of various sorts that wasn't as effortless to comprehend and use as it could have been.
An important distinction is that if I didn't really believe that Joomla! was created by intelligent and thoughtful people that really care about their program, its users's, its documentation, etc, -I wouldn't bother to write this.
I was impressed by the webiste, and the bright and friendly message it is sending, and I was encouraged by what I read (on the website and in outside reviews) about Joomla!'s ease of use/learning for beginners. So I am disappointed, and disheartened that I have run into trouble so early on.
Any percieved or real sarcasm and belligerence on my part is either to lighten the mood, make my point, or, it comes more from past frustrations than from this current one. ]
That said, I will now quote Frank Costanza [from the Festivus* episode on the tv series Seinfeld]:
"I've got a lot of problems with you people! And now you're going to hear about it!"
*before a Festivus dinner there's an "airing of grievances". "You gather your family around, and tell them all the ways they have disappointed you over the past year."
I looked over the Joomla! website, and then started in earnest on the "Absolute Beginner's Guide". I saw the "absolute" and (seriously) thought "Great. Its not just a "beginner's guide" like other supposed "beginner's guides" I have used in the past., -it might actually be a guide for true absolute beginners. I hope it is!"
Although the word "absolute" was encouraging, I quickly found it to be just that (a word).
When software makers write an 'absolute beginners guide' it invariably doesn't explain enough, and go basic enough for people who don't know what the things being talked about are, and why they should do certain things. Things need to be spelled out simply. And ideally the writers should have an absolute beginner or two read through the document(s) and see where they get lost. Notice I didn't say "if".
Let me explain something to you:
You know how to do these things already. People reading the manuals/guides do not. If we knew how to do the things, we wouldn't need the manuals. There are people who are familiar with all this stuff, who just need to read quickly over the manual, and then maybe consult it as a reference. But us beginners are refered to this and other manuals/documentation, from an ABSOLUTE BEGINNERS Guide to Joomla!.
And its not like us beginner's have already worked our way through most of the Absolute Beginners Guide by the time we are told (albeit a bit indirectly) to read the Installation Guide. Not at all. I clicked on the first link in the first sentence of the guide, and started reading the Joomla! v. 1.5 Quick Start Guide. I read the one paragraph introduction. So far so good. And then on page 4 [virtually page 2 of the text] I encounter instructions to do things including installing server-related programs on my home? computer, -with no beginner level/ beginner-understandable explanation of the situation; the intended project and its purpose; the terms; the implications of these installations, or the differences between the choices. Also there is no mention of where to find sources of information on these topics, other than to consult the Installation Manual.
So I started reading the Installation Mnaual hoping that it contained the information I need to understand the situation and the things involved.
When I got to the page titled "Localhost or Remote Host Installations", there are exactly two sentences in the opening section on the 'local host' option. So I read the next section on remote hosts and then I got to the red box which contains some clues. [<my use of the word "clue" should be a red flag here. This isn't supposed to be an unsolved mystery case or a treasure hunt.] I then read the rest of the page including the yellow box, which offers a bit of somewhat-more-clear info.
So after a lot of unecessary work I think I have pieced together an idea of the situation. I have already spent way too much time reading and re-reading the available paragraphs in the mentioned sections of these two doucments, trying to read between the lines and figure out what the situation is. I also read a few wikipedia pages.
Please correct me if I'm wrong, but here is what I think is the situation:
Apparently the activity in the Quick Start Guide is to make a sample website using Joomla! after installing the server programs [collectively called _AMP], on my 'local' -aka home/personal-computer. Apparently there are what are called "instances"? of _AMP, which are separate installations of _AMP and Joomla! which must be done for each website?
Apparently XAMP is an easy to install/configure version of _AMP that one can use on their personal computer to create, develop, and test-run webpages, websites, and technologies, -before putting them 'live' on a real server which runs another incarnation of _AMP such as LAMP (if its a Linux server).
I still am not sure if I have all this correct or not. If it is correct, I could not have figured it out if I had any of the following A) less patience, B) less intelligence, C) less will to succeed at this, D)less lifetime experience struggling through shall we say 'less-than-ideal' documentation of various other programs, operating systems, home appliances, etc.
I STILL don't know whether or not one can make a website on a local host/ XAMP setup, and then transfer that website to a real live shared web host.[assuming the chosen web host meets the requirements] Does this work even though the server is going to be running something other than XAMP?
Later I read the rest of the Beginner'e Guide and it clarified the fact 'localhost' does mean my home desktop computer.
It also says "...a test environment before updating your live site." but does this mean that I can only add the things I make on my local setup to a website thats already on a live server? Or can I make an entire website in the local/XAMPP setup, get it the way I want it, and then 'export' it to a live server running a live _AMP?
There is a basic phenomena that occurs near universally in the realm of educating, and its a phenomena that the educators are usually un-aware of. The phenomena is as follows:
The educator doesn't give much, if any real, deliberate thought to what the student already knows and doesn't already know. And if they do, they don't act using this.
You can't walk up to someone and say "Go boil water. Use that pot." if they don't know what water is, boiling is, and they have only a vague idea of what a pot is." Furthermore you didn't even mention that they should use the stove, and more fundamentally, they don't know the why. They don't know that we're going to make oatmeal and that this is accomplished by boiling the oats in the water. Hopefully they have a chef friend, and/or there's a wikipedia page on how to boil water and why one might want to do this.
Another broad example:
You can go up to a brain surgeon and say "The patient has a malignant tumor above the left cerebral cortex. Operate." -and he/she knows what to do. If you said the same thing to someone on the street they would uh, need more information. (namely medical educational/training).
Back to the Installation Guide: I continued on, thinking that the pages below might explain/ teach what I need to know.
When I got to page two of two in the "Localhost or Remote Host Installations" section, -[I almost missed it since there is a "next" link tucked under the end of the last paragraph on page one of two, and my initial instinct was to click the other next button down below as I had done for the last several pages.]- I was advised to "check the installation." Assuming I was confident with the clarity with which I understood what I was supposed to be installing and why, -and had already installed something, -there really isn't enough information for an absolute beginner to do this check. To your credit there is a link to an explanatory page and a glossary. But before I even get to that, you are talking about doing something that involves "simply creating a PHP script". Oh, why didn't you tell me all I had to do was create a PHP script? -as though I know what that is, let alone how to "simply" create one. You might as well say "simply operate on this patient's tumor."
I realize that you go on to say a bunch of words that are equally useless to me, and that these words probably explain how or where to create the script. But a scene from the tv show The Big Bang Theory comes to mind where Caltech theoretical physicist Dr. Sheldon Cooper is talking to his 'non-science-aware' next door neighbor Penny. [the last line is what is poignant here.]
Sheldon: "I need your opinion on a matter of semiotics."
Penny: "I'm sorry?"
Sheldon: "Semiotics--the study of signs and symbols as a branch of philosophy related to linguistics."
Penny: "Okay, sweetie, I know you think you're explaining yourself, but you're really not."
Thank you Penny for putting so elequently (and comcially), something that I feel all the time as I make my way in the world of learning computer software/protocols/interfaces!
Another point I'd like to make is that you won't get the feedback from people who couldn't easily make their way through your manuals and guides. They will either search for outside sources of written information on the subjects, and/or ask many questions on forums, (and sort through the often inclomplete, confusing, incorrect, and/or conflicting answers they get), And/or they know someone that helps them out big time. And this knowledgable friend may even practically do the whole thing for them, and they never learn it.
You should know that there are people [I being one of them] that ACTUALLY WANT TO LEARN THE PROGRAM FROM THE DOCUMENTATION. -with minimal forum posting, and NO knowledgable friends.
I realize due to the complexities of computer systems, software, protocols, hardware and the combination of these, -there are going to be some specific issues that one is going to have search the forums for solutions to. I'm talking about the basics.
The manuals/guides should start by laying everything out clearly, explaining terms, choices, implications, -and then build layer by layer from there. Anything outside the scope of the document should have referenced sources, and people reading it should not have to say "Wait, What?" on EVERY OTHER PAGE.
As anyone in the realm of web site management knows, when people come across a problem with a website they will go to all sorts of convoluted lengths to achieve their goal, such as copying and pasting urls, google searching the site for a page they can't navigate to, etc. They will have been doing this for weeks and months before you somehow find out that there is a problem, -because no one will tell you.
Its the same with documentation. People will do anything up to and including enrolling in a technical college, before they will tell you that they couldn't learn what they needed to from your manual.
Note: Please don't say that the Installation Manual is meant for people who have already learned quite a bit from the other manuals about the subjects and processes invloved, -because- as you can see from my experience, someone can start with the first paragraph of the "Absolute Beginners Guide", go to the Quick Start Guide, -as is advised in the beginner's guide I will point out. And then upon promptly being lost in the Quick Start Guide, they consult the Installation Manual, -(as it is linked to in the Quick Start Guide.)
So people have only read several paragraphs when they are dumped off into the Installation Manual which is over their heads.
If the Beginner's guide was properly written, you wouldn't need a Quick Start Guide. Quick starts are for people who don't have the attention span or the patience to read a proper user manual or beginners guide.
I don't want a quick start. I want proper education and instruction!
If your sentiment on the matter is that people should learn the basics elsewhere, I somewhat agree with you. I think that one should learn as much fundamental information as they can elsewhere.
But why advertise the guide as being for absolute beginners, when it is far from it? Its just a tease.
Furthermore, I already have a basic understanding of internet protocols and so fourth, and I already did a fair amount of reading on the subjects of websites, webhosting and so fourth. Otherwise I would have been utterly lost.
The bottom line is why portray your system as easily learnable by a near-complete beginner, if you're not going to provide the instruction with which they can accomplish this - easily.
I'll end with a quote from Chuang Tzu.
Begin right and you are easy.
Continue easy and you are right.
The right way to go easy is to forget the right way,
and forget that the going is easy.
I challenge you to make a guide where it is effortless to forget that the going is easy (because it so easy to read through).
Thanks for reading. I look forward to your responses and comments.
I'm open to suggestions on how to proceed in my learning about Joomla!.