The Joomla! Forum ™

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!.

I think that's the most important part of your post. If I remember correctly, the absolute beginners guide is a collection of various documentation written by high school students for the Google Highly Open Program?.

It's great to have someone like you who reads the guide and realizes: Hey! something is missing here.

What you can do is not only tell us that something is missing, but once you learn how to do that something, add it to the documentation. It is a wiki after all.

Maybe you can come up with a list of things that you saw were missing from the documentation. After all, the better documented Joomla! is, the less support questions we should have over basic features.

_________________
Backup, backup, backup!
The "Master" .htacess file by Nicholas http://snipt.net/nikosdion/the-master-htaccess

Please also note we can't be all things to all people. You have a bit of a responsibility to look up things, do some research and educate yourself. Having a presence on the web is a big thing. Encompasses a ton of information. If you came across a term or a concept that you don't understand, I would suggest doing a google search and getting yourself a bit more information on it.

Geoff's suggestion though to get a list of things you think would be helpful is a good thing. Everything can always be improved, and constructive criticism is always appreciated.

_________________
Co-author of the Official Joomla! Book http://officialjoomlabook.com
Marpo Multimedia http://marpomultimedia.com

i slightly agree on both camps.
does it need a top 10/20/30/ questions ?
its annoying for people when people expect you to do all the work for them http://forum.joomla.org/viewtopic.php?f=48&t=445697&p=1870242#p1870242

I also agree that some of the topics in the wiki (that few people use) needs updating. perhaps when i have more time than trying to pull hens teeth looking for the required information to help people i could go through some things and highlight them, but just when you deal with one, 10 more come along.
an idea for the documentation WG perhaps?

_________________
HU2HY- Poor questions = Poor answer
Un requested Help PM's will be added to the foe list and possibly just deleted
{Community.Connect Administrator }{ Showcase & Security Moderator}

You may not be fully aware of what a rosy and encouraging picture is being painted by the various pages of the Joomla! website.

My story might be typical of many beginners who discover Joomla! The sequence was as follows:

I was sorting through web editors trying to find one that had the features to make a website with the components I wanted it to have. First I found a supposedly easy one, but it lacked at least a few features (maybe more, I never installed/ tried to use it.) Then I found another Web editor that had the features, but after attempting to find out if it was beginner-usable, I got the picture that it isn't (although I'm still not sure about that one.) [f.y.i- the programs were Kompozer and Quanta Plus]

So then someone in a Linux forum suggested going with a CMS, like Drupal or Joomla!. I looked into Drupal, which was described in various online sources as being not-the-most-user/beginner-friendly. So then I looked into Joomla! and “Hey! I like what I'm reading here. Based on the impression I'm getting from these webpages, reviews etc. -it sure sounds like I'll be able to do this!”

Now, this process of researching various ways of creating a website took me several days, and consisted of more than the few dead ends mentioned. So I was quite glad to have found Joomla! And I still am. But it is no where near as easy as it is made out to be. I still can't comment on the program/system itself becasue I'm still trying to install it.

After deciding on Joomla! I looked over the website and “Hey, great! There's even an “Absolute Beginners Guide.” I'll start here.” So several long days later and here I am.

I will now list some excerpts so anyone reading this can see what I read that lead me to believe -naively perhaps- that Joomla! might be easy. I should point out that I thought to myself “Maybe it won't be as easy as its made out to be. But, its free (money-wise), and its an open-source project, so why would they mis-represent it? If they were selling the software I could see why they might exaggerate things. but not if (greed) isn't a factor.”

On the 'about page' of joomla.org I read:

[second paragraph]

“A major advantage of using a CMS is that it requires almost no technical skill or knowledge to manage.” ha!

[further down the about page: ]

I need to build a site for a client. How will Joomla! help me?

Joomla is designed to be easy to install and set up even if you're not an advanced user. Many Web hosting services offer a single-click install, getting your new site up and running in just a few minutes.
Since Joomla is so easy to use, as a Web designer or developer, you can quickly build sites for your clients. Then, with a minimal amount of instruction, you can empower your clients to easily manage their own sites themselves.

[at the bottom of the about page: ]

Joomla! seems the right solution for me. How do I get started?

Joomla is free, open, and available to anyone under the GPL license. Read Getting Started with Joomla to find out the basics then try out our online demo and you'll quickly discover how simple Joomla is. If you're ready to install Joomla, download the latest version here you'll be up and running in no time.

- - - -
On the main page “Joomla! Official Documentation”,

[in the upper right corner: ]

As someone who has not used Joomla before, it is likely you have no clue how to get started using it.
.... If so, you are just starting a very enjoyable journey and we warmly welcome you to Joomla and encourage you to read the Absolute Beginner's Guide to Joomla!

(my journey is not enjoyable yet.)

- - - - -

On the "Absolute Beginner's Guide to Joomla!":

NOTE: nowhere at the top of this document, -or on the Joomla! Official Documentation page that directs you to the Absolute Beginner's Guide, - is there any reference to the fact that it was mostly written by High Schoolers in some kind of contest.

[At the bottom of the page, it says: ]

Most of this material was written by Joomla! Google Highly Open Participation Contestants. This work is of the highest quality and the students were inspiring to work with. Sincere thanks to all of our participants for sharing their gifts with the Joomla! community. You guys rock!

So my question is: do you really believe that this guide is of the highest quality?

“Highest quality” considering it was written mostly by high school students? Or highest quality period? Or do you mean “highest quality” as in it lacks speliing errors and was turned in on time, (But not as in “highest quality beginner-level instruction on installing and using Joomla!” ? )

The real question is do you take yourselves seriously as open-source software professionals? And I don't mean “profesional” as in making money. I mean the higher sense of the word professional, as in “professional quality wotk” and “professional integrity”.

I'm tired of hearing how free open source is every bit as good as proprietaty, and even though they don't get paid, the people who develop the software and contribute to the open source projects take it very seriously, and the work gets done because so many people are involved and collaborate......

Is this how seriously you take your documentation? - “Lets just have a contest and let some high school kids write the beginner guide.”

If the anwser is “we're too busy”, ok. But 1) don't put the idea out there that its going to be easy to install and learn Joomla!, and 2) warn people that the guide isn't what it could be, and that its largely the result of a contest.

In the first paragraph of the Beginners Guide, it says:

This is a well developed and efficient training guide and video set.

So either A) the high school students wrote this endorsing sentence, or B) you wrote it.

In any case you published it on your website, front and center, in case anyone has any doubts as to whether this is going to be a high quality, easy-to-follow guide.

I don't necessarily want things to be easy, or 100% efficient, but just effective, thorough, do-able.

I don't mind looking up a term, or googling an error message, but to be told its easy for beginners and then to stuggle at every little step*, at a loss as to where to find the info, -thats not very fun. Its discouraging.

(* and before I even get the system installed/configured)

Yes I'm going to have to look things up and do outside/independent learning. For example, in order to create anything more than a basic website, I'm probably going to have to modify, if not write, a PHP script. So I'm going to have to learn the basics of PHP and the PHP script language. But right in the process of installing the programs, I'm told to create some PHP configuration script file. All I want to do is install the system, so I can do a practice webpage as described in the beginner level guide. But already I have to learn PHP. Maybe I don't have to actually learn the language, maybe all I have to do at this point is create and save a simple script that is already written for me. But in the guide it doesn't say what program to open to paste the text into, and exactly what to do.

Think of a young child who is trying to learn to hold a cup, (and he/she doesn't know how to walk.) Its frustrating for the child to hear “walk over there and read that book on how to hold a cup.” Lets say the child knows how to read, so that isn't the problem. The problem here is that the child signed up for an “Absolute Beginners Class on Cup-Holding”. So he/she says “I thought, based on the fairly explicit name of the class, that you were going to take me through the necessary instruction.” And the instructors say “Sorry, maybe you can google some stuff and figure it out yourself.” So the child says to him/herself: “Hmm, what a misleading course title. I'm glad I didn't pay any money for this, but still there's the emotional let down/disapointment, and now the frustration of struggling through all this virtually on my own. I really thought I'd be holding a cup by the end of the day.” So then he/she manages to crawl over to the computer in the corner, and google “how to open a book.” [because remember: he/she can't hold a cup, so he/she doesn't know to hold or manipulate a book either.] So after struggling through a guide on “how to hold a book” -which was hard because he/she isn't all that skilled at reading either- he/she crawls slowly over to the book on “how to hold a cup”.....

~
What does this story illustrate?

Life's hard. No one said learning how to hold a cup was going to be easy. -Oh wait, they did. It was implied in the title of the class: “Absolute Beginners ...”

Its not just the Joomla! website either. There are other sites that decribe Joomla! as being easy for beginners. Its almost like there was a campaign to portray Joomla! as beginner-friendly. Either that or people really believe its beginner-friendly, and came to this conclusion on their own. Its quite possible that they just saw that there was an “Absolute Beginners Guide” and assumed that Joomla! is therefore beginner-friendly.

I do find the community to be friendly. Nobody told me to go to h__, or to use a simpler program. And an obvious effort has been made to cater to the needs of beginners and welcome them. Its just that I'm tired of hearing how everything is easy for the beginner, when its not the walk in the park that its made out to be.

I don't like asking a million quesions in forums. Not to mention waiting hours, sometimes days for responses. I want a little dignity, not having to post every little error, and ask for help at every step.

It seems to me that if everyone involved in answering the literally thousands of posts would just take a few days off and work on a beginners guide, -Joomla could probably have the best d___ absolute beginners guide on the planet (perhaps literally).

People who are capable of not only understanding, but creating, complex computer software systems can surely manage to understand what needs to be in beginners guide. Can't they? Surely they don't need me to tell them. Right?

To me its a shame to make a great system, present it as being beginner-friendly, but not make an equally great manual.

If you made a million dollar museum, and highlighted in the brochure that it is handicap accessible, and then put up a sign that says “Handicap Entrance”, -wouldn't you also take the time and expense to make a proper ramp and door? Or should the handicapped learn to walk, and then climb up the steps like everyone else?

They might have stayed home, if not for the brochure inviting/welcoming them.

~

Analogies aside; What I'm overall 'hearing' is basically “Somehow learn about the processes, programs, systems, terminology, etc, and then you won't be a beginner anymore and you can just consult a user guide like us non-beginners.

a note on the word guide:

I guess there are varying senses of the word 'guide'. Technically one sentence could be a guide. Its one little clue that helps guide you on your way, -a signpost (but nothing more). There is another sense of the word guide that I assume when I see “Absolute Beginners Guide”. Its an image of a guide holding the arm of a blind person, helping them along at every step. They don't know where to go, and they can't see where to go, nor see where they are, nor see where they're going, -so they need a guide.

- - - -

I would be interested in taking the time to work my way through the guides and tell you what is missing. but only if you promise to add the missing information to the guide. Actually I think it needs to be written from scratch. There's not enough flow. Its too fractured. Its too wiki. A wiki, a beginner guide does not make.

I'm happy to discuss any of this further.

I don't want to seem ungrateful. I appreciate that people have made a software program, a website, documentation, forums.

I just don't like people selling me a car with a giant icecube in the trunk and telling me its got air conditioning.

Wow what a long post. No one sold you anything as far as I can tell. If you don't like the beginner's guide please feel free to create a new one. You would be the perfect candidate to document things as you go along.

_________________
Co-author of the Official Joomla! Book http://officialjoomlabook.com
Marpo Multimedia http://marpomultimedia.com

First of all, thank you for posting your comments about your experience with Joomla and its documentation.

A beginner's perspective is particularly valuable to us documentors as it is something that we generally lost many years ago and it can be really hard to see things as they (you) see them.

I'm well aware of the shortcomings of the Beginner's Guide and I think that others are too. In the past year or so many people have volunteered to re-write it, but sadly so far only very minor improvements have been made. This is an area where newcomers can make a real contribution to the project and I'd like to encourage you to help us get there.

You seem to enjoy writing, which is a useful quality for a documentor, and you are a beginning Joomla user, so you would seem to be an ideal candidate to help us write a better Beginners Guide.

I'm not suggesting that you completely rewrite the manual, since that is clearly a mammoth task, but you could, for example, create a list of terms or concepts that you didn't understand, or tell us what information would have made your journey easier had you known it earlier. This can then be expanded on by you and others, until we get to the stage where parts can be incorporated into the Beginner's Guide. You can add this to the wiki, perhaps in your user page to begin with. Sadly I had to lock the Beginners page because it was attracting a lot of spammers, but if you feel up to the task of editing it directly then just ask and I can give you write permission for it.

Of the many points you make I'll pick up on only one, because it made me smile:


Actually, they (and I) do! Developers generally make terrible documentors and as a developer myself I can tell you from personal experience that writing for beginners is really, really hard. Technical writing is simple by comparison (and for a geek like me, vastly more enjoyable to boot). Perhaps that's why there are more textbooks written than novels. One of my favourite quotes is from G K Chesterton: "What's easy reading is damned hard writing". I know exactly what he means.

Regards,
Chris.

_________________
Joomla Leadership Team - Production Working Group

Joomla Web Services http://www.kickstarter.com/projects/964120480/joomla-web-services
Lion Coppice http://www.lioncoppice.org

Chris, ( and other interested parties )this may be sticking my head out, and i would have posted on the joomla-wg mailing list. but if a new "janet and john" manual is required. then i am willing to assist.

_________________
HU2HY- Poor questions = Poor answer
Un requested Help PM's will be added to the foe list and possibly just deleted
{Community.Connect Administrator }{ Showcase & Security Moderator}

Thanks mandville. Yes, I'd love to see the Beginner's Guide improved. I'm open to suggestions on how to go about it, but perhaps you could start by putting together an outline of the topics that a beginner would need to cover. This can be fleshed out later once a suitable structure has been determined. There are lots of interconnected concepts that need to be covered and the first challenge will be to tease them apart so that the guide can introduce them in a logical (or rather, beginner-friendly) order.

It's also important to know the level of prior knowledge that can safely be assumed. For example: can we assume that the reader knows what a web browser is? Can we assume the reader knows what a server is? And so on. I wouldn't want to set the bar too high, but the lower you set it the harder and more time-consuming it becomes to write.

Thanks for volunteering.

Chris.

_________________
Joomla Leadership Team - Production Working Group

Joomla Web Services http://www.kickstarter.com/projects/964120480/joomla-web-services
Lion Coppice http://www.lioncoppice.org

The ideal scenario is the beginner starts out knowing little if anything and they learn everything they need to know as they work their way the guide.

The necessary information is presented to them in the necessary order, one thing after an other.

It is my understanding the average user of Joomla! wants to learn to use it to make websites.
There are many subjects involved here including websites, _AMPP, CMS's (namely Joomla!), FTP, etc. Obviously a beginners guide will not include every exisiting bit of knowledge on the subjects of relational databases, webhosting, HTML, CSS, OS's, scripts, etc etc

So the question is what does someone need to know to use Joomla! in an average way?

I of course don't know the answer to this question at this time.

I obviously couldn't begin to write a guide from scratch because I haven't installed or used the program yet. But I can go through the existing guide as you suggested, and tell you what I think, see, feel, observe.

When I start reading down the Beginner's Guide. I notice that its mostly what I'll call 'niceties'. I actually think these niceties are well written and they really do put one at ease. However other than the niceties one only learns a few things about Joomla!. (in the first few sections)

-It is a Content Management System (CMS) platform.

-It is a well-tested, extensible and effective tool.

-It has something to do with websites. Note that the guide doesn't expressly state that Joomla! is used to create websites. If you didn't aleardy know this you'd have to read between the lines. Although phrases like “building your Website” are used, its not clear exactly how Joomla! fits in to this.

So now I've read down to where it says: “Complete the Joomla! v 1.5 Quick Start Guide”. I've learned very little. There are several 'options' to go on side journeys though. There is the link in the first paragraph to go to the Quickstart Guide. Also the link to the video acompaniment. There is a chance to go play around with Joomla! on a demo site. There is the Joomla! Core Features Guide. A few more 'niceties' (again, well written and comforting and serving a de-stressing purpose quite well I think), and then we're back to a second recommendation to complete the Quick Start Guide.

Now, I skipped the Quick Start Guide the first time because the beginner guide said “If you do nothing else”. I wanted the full learning experience, so I planned on completing it later. So I continue on with the Beginner guide and get to the Demo Site option. I say to myself “I could see that some people might want to try Joomla! out, but since I've never used any sort of web creation software in my life, I probably wouldn't know what to do. So, I'll continue on and just go ahead and learn how to install Joomla! and then learn how to use it.”

I continue along and I get to the Joomla! Core Features Guide. I think to myself “Maybe some people would like to get a sneek peek at the feature list, but I wouldn't know what much/most of it is. So I'll skip it and I'll learn about the features when I get to them later on.”

Then I read down to where the “planning your website” link is. I went and completed the questions at the top . It was helpful in planning various aspects of my (hopefully soon to be made) website. Then I read the rest of this page. It contains some info about Joomla! and what you can do with it. The page also has a lot of “niceties”. I should have mentioned this page in my above post. This page really pumps you up with the idea that its going to be smooth sailing.

It seemingly gives quite a bit of information. But a beginner is not going to comprehend all of it in a real way. So its mostly a “shotgun preview of coming attractions” -so to speak.

The last section of the Planning Your Website page is basically more assurance and encouragement. Note the last paragraph:

“Please, don't let any of that scare you off. This is the Absolute Beginner's Guide to Joomla! and you will learn what is needed if you invest a bit of time in reading and trying out these ideas. Now, should we begin?”

When I see the last sentence I think “Oh good, we haven't begun yet. I haven't really learned anything much yet, so I'm glad we've yet to begin.”

Back to the Beginners Guide and I again encounter a recommendation to do the Quick Start Guide.

When I go to the Quick Start guide it will have me install a localhost instance of XAMPP , install Joomla! and then make a practice website.

There wasn't enough information for me to be able to do the installation. For one thing, what info is there is for a Windows installation. If you're installing XAMPP on Linux (as I was) you get to the read the following lovely paragraph:

Note: The following instructions are based on a Windows install. Other operating
systems will be similar but slightly different. Please refer to the XAMPP installation
manual for your operating system.

But even if I had been able to complete the Quick Start Guide, and do the installations and exercises, - I would have been doing all this “in the dark”. I would be doing all the installation and practice BEFORE knowing what Joomla! is, or what _AMPP is, or a what a CMS is, or the basics of how the whole system works.

Back to my experience, I see that in addition to the Note on “Other operating systems”, there is also a mention of the Official Joomla 1.5 Installation Guide. So I went there and worked my way to page 2 of 2 of the “Localhost or Remote Host Installations” section. At this point I had Joomla installed, and I selected English for my language. But I had some Red entries in the next screen [aka things that needed fixing]. I couldn't find out how to fix these things. When I got to page 2 of 2 in the Installation guide it had glossed over these installation steps and was on to talking about creating a PHP. I didn't know what this was, or why I was supposed to be doing it, -despite reading the text several times. In any case I hadn't finished the installation steps.

So as I was reading info elsewhere on the internet in attempts to learn what I needed, I came across something that said you should check the top of your XAMPP screen to see if there are errors. I checked and there were errors. I googled them and it turns out I had installed XAMPP 1.7.2 which contains PHP 5.3 It turns out Joomla 1.5.14 doesn't work with PHP 5.3 The Joomla! Installation Guide I looked at earlier didn't say not to use PHP 5.3 and I had checked and rechecked to make sure the XAMPP I was getting met the requirements for Joomla!.

I eventually learned that I'd have to uninstall the whole thing, and install XAMPP 1.7.1 which contains 5.2.9 which works with Joomla.

I did the installation of XAMPP 1.7.1 and then ran into problems with installing Joomla. It was something with Linux not recognizing a directory. I got some help at a Linux forum and now I have installed Joomla! and selected English as my language. I have no idea how to finish the installation/configuration.

If I leave the Installation Guide and the Quick Start Guide, and go back in the Beginners guide, I see that there is link to a thing called “Learn Joomla 1.5 Fast”

Maybe I'll try that one tommorrow.

~
Let me know if this is helpful to you.

I might help with the documentation in the future.

To comment on the questions in your last post Chris:

I think most beginners know what a web browser is, but including the words “[e.g. Internet Explorer, Firefox]” can remove all doubt in the mind of an unsure reader. Of course this only has to be done in the first use of the term in that document.

As for knowledge of servers, one sentence can tell people what they are.

Something like: A server is a computer that has webpages on it and serves them to individual computers that request them over the internet.

As for this whole _AMPP thing, I have only a basic idea of what it is. Whatever vagaue understaning I have of it, I really didn't get it from the Joomla! website. I had to read a bunch of wikipedia pages and try to understand what I was reading.

I don't even really know what Joomla is. I know its a CMS. I read webpages elsewhere about CMS's and I know basically what they do. But when I see “web application” I don't have any solid knowldege or frame of reference for that.

Apparently you have to make a database to put the “content” in, so you can “manange” it. Even the term database is foreign to me in this context. I think of a database as being something like a spreadsheet with rows and columns of mostly numerical data.

I can't really visualize webpage material as “content” in a “database”. But then I don't I have even the most fundamental knowledge of this whole system and how it fits together and functions.

I see your point about how writing guides for beginners is hard. Baiscally at every step say "What do they need to know/learm to understand this?" and then after you write something say "Would they know enough at this point to understand this sentence/paragraph and the terms and concepts therein?"

I know these posts of mine are long. I hope they are at least somewhat insightful for your purposes.

a riddle:

What's red and green and way too hard to find solid information about?

the answer:

the "Pre-installation Check" in the Joomla! Installer

~

I'm having 'a little trouble' finding comprehensive information on how to get the little red “NO” and “ON's” in my Joomla! pre-installation check to turn green.

I'm not alone.

I did a google search with the following words:

Joomla installation "Pre-installation Check"

The first google result was for the Joomla! forum. You can see in the sub-results that there are several threads by people having problems with this. If you click on “More results from forum.joomla.org”, google displays a page of such threads. If you look down at the google results page numbers at the bottom, you'll see that there are 10>> pages. If you look through the myriad pages of results you'll see that they are in many languages!

People all over the world are having problems with this!!

And these threads go back at least several years!

Think of the hours and hours of human life that could have been spent doing something other than making forum posts and googling for info on the Joomla! pre-installation check.

If it was adequately documented in the various Joomla! guides and manuals, (even one of them), -I and the other people around the world wouldn't have had to post in forums and/or search for hours.

If you read the threads, you see that some of the people just give up. The thread remains unsolved. An everlasting testament to the will-breaking nature of the Joomla! pre-installation screen and its lack of comprehensive, adequate documentation. “I was hoping this would be easier to install, like a game or office application.” -one discouraged person said. (paraphrased) Some people,- on page two or three of the thread- decide to leave the entries red and just install anyway. Veteran Linux gurus remain silent, having exhausted their knowledge. Joomla! pros are reduced to saying “Hmm, I don't know. The installation process was easy on my computer.”

And the relatively small range of variation in these threads is matched by the small variation in the aloof way with which the various guides handle the matter of these pesky red menaces.

One guide I saw online “covers” the issue with this smooth move: [note the last sentence]

- - - - quote

If any custom settings are enabled for your account this might interfere with the Joomla installation. In such case the pre-installation check will notify you exactly which requirement is not met, the status will be marked in red and if available more information will be displayed. If so the issue must be resolved and the check run again.

- - - -
“resolve it.” -Thanks for the detailed guidance!

Do I just go to a command line and type “problem resolved” and press enter? Will that work in Linux as well as Windows?

They could have saved time writing their guide and just wrote: “Welcome. Learn how to install and use Joomla. -The End-”

You might be thinking: “Maybe they wrote more about the subject later in the guide.” I must admit I didn't read the rest of it. But, A) the next sentence was: [see below]

- - - -quote

Once all checks are successfully passed you can proceed with the installation by clicking the [Next] button.

- - - -

-and B) there was no mention of any other place in (or not in) the guide to refer to for the needed information. So I'm assuming “resolve it” it was all they provided on the matter.

I like how some of these guides include a screenshot of their pre-installation check with all the items green, as if to say “There's nothing red on our preinstallation check. So like whats your problem loser?”

There is a myth going around in the various forums and guides that Joomla! -quote- “walks you through the installation process.”

What the h--- are these people refering to exactly?

“Walks you through it” usually means there is info and hints, and everything is laid out for you at each step. What is on the Joomla! pre-installation check screen couldn't be further from “walking you through it.” In the bottom section there's a single paragraph applying to all the entries, and its not even clear as to whether or not the items need to be rectified or not.

Instead of the nice stroll through the park that people make it out to be, I feel like someone led me into the park, told me to take my shoes off, and then they grabbed my shoes, said 'I'll be right back', and then ran like h---.

There's absolutely no “walking” being done. Its more like sitting under a red and green Christmas tree hoping that Santa Clause will come down the chimney with his elves and finish the installation for you.

And it kind of feels like Christmas eve too, because its past midnight, the lights are dim, and everybody but you went to bed already, but you're still up trying to figure out how to change the stupid entries in your pre-installation screen. Ho! Ho! Ho! Merry Christmas to me!

I'm starting to feel like I'm the un-witting star in a reality tv comedy special: “Lewis Black attempts to install Joomla!”

Allow me to continue my coverage of the ways that various Joomla! guides handle the cryptic “Step 2” of the Joomla! installation process.

In the the guide “Learn Joomla! 1.5 Fast” the author employs a brilliant documentational technique,

- - - -quote

The first step lets you select the language for installation. Click “Next‟, and you will be shown a screen with all the settings of your web server and whether they are good for Joomla!. Click “Next‟ to proceed.

- - - -

NEXT! In case you didn't pick up on the author's stealthy, subtle brilliance, -the technique used is to skip the matter of rectification all together. Wall of silence. The old “skip 'n' scoot.” -Well played author, well played.

No mention of what happens when there are settings that aren't “good” for Joomla!.

Other guides, tutorials, and manuals employ one or more similar tactics from the same bag of tricks.

One exception is the Joomla! 1.5 Installation Manual.

It refers you to a section towards the end of the document titled “Known Issues & Error Handling”. This section is one and a half pages long and I'm being generous with the 'half.'

Although it appears to cover a few of the most common pre-installation check issues, there are a few deficiencies -lets say.

-One, a beginner such as myself isn't going to be able to do the things mentioned.

-Two, If you look at the various forum posts, you'll see that it isn't at all simple, even for advanced users.

If you have red entries other than the “most common” ones, -theres nothing there for you at all.

I refer you to the light blue box at the start of the “Known Issues & Error Handling” section. It states that the Joomla! documentors are “holding off “on this section until some later date. Presumably that date is 2099, the year when computers are implanted in people's brains and all they have to do is 'think' a webpage into existence.

Seriously though, here is what the box says:

- - - -quote

Note: We are generally holding off on compiling this section until the final release of Joomla! 1.5 is made.

We will add obvious repetitive issues that have a common thread in the forums as they arise, or are identified
by the Developers and Quality and Testing Work Groups.

- - - -

What do they mean they are waiting for the final release?

I guess they're waiting for Joomla! 2.0 ?

If you look at the title page of this document, you'll see that it was last updated 30 October 2007. -Thats IF you managed to find the Version 0.5 Installation Manual. There is at least one other (older) version linked to in the website and its subdomains.

If we look at the changelog, we see this entry:

15 Oct 2007 Added .htaccess & php.ini detail to Error Handling section

Here's a challenge to the Joomla! User Documentation Team. Make a new entry in that sparse log:

30 Oct 2009 Fully updated Known Issues & Error Handling section, now adequate

~

Despite my difficulties I hope to complete my easy, beginner-friendly, 'walk-in-the-park' installation and go on to make some great websites.

For now, this thread is turning into a blog.

It might be the closest thing I'll ever have to a website.

I hope not.

I can't read posts that are so long and complex to focus my eyes on .. and you're the same person saying the Joomla install is confusing.

How can something like how to contact your host, or how to modify files on various different operating systems be documented in a single install.. it's just not practical.

Do you have experience with other systems/software on the internet? Could all of this 'ranting' just be to vent because you are using a poor host that doesn't offer an environment suitable for Joomla? If you are having this much trouble with Joomla.. you obviously have little to no experience at all with internet/server software.

Have you tried to proceed with the installation despite the warnings? Why is it Joomla's responsibility to educate webmaster on things that should already know? Why don't you use a host that has a one-click Joomla installer?

I'm not saying things can't be improved, but the way you are going on about it is hardly the best way to help things improve. Besides.. you're wasting so much time on a something that is 90% of the time a less than 5 mins task... and how long must these posts of yours take to write.. and then how do you feel when people can't even make sense of them with the double paragraph spacing or whatever technique it is you employ...

/me goes off rubbing his eyes

_________________
Brad Baker - Follow me on Google+
http://www.rochen.com - Joomla! Hosting, the correct way.
http://www.joomlatutorials.com <-- Joomla Help & Tutorials
^Now with Joomla 2.5 and Joomla 3.0 Tutorials

Hi Brad,

[just in case this post is so long that you decide not to even read it,

1) I think you'll find this one easier to read.

2) -spoiler alert- I partially agree with some of your above points by the end of this post. ]

I'll address everything in your post.

Yes I agree that the writing in my above posts isn't the easiest to read. Other people apparently read them. I think it has something to do with how much one is open to hearing what is said in them.

As for the second part of your first sentence, I'm not sure what you mean by “same person”. If the post says “serenity now” for the name -that's me. I am indeed a person who is saying the Joomla! install is not easy for beginners. Also, judging from some threads I read, some advanced users don't have the best time of it either.

In regards to your second and third paragraphs: If you read my above posts -which of course nobody expects you to do- you will see that my general message here is that Joomla! has been presented as being easy to install and use for the COMPLETE beginner, but I think this is not so. I cited multiple examples of text on the Joomla websites that paint a rosy picture of how easy everything will be for the beginner.

In the last sentence of your third paragraph you say the following:

----quote

If you are having this much trouble with Joomla.. you obviously have little to no experience at all with internet/server software.

-----

If you had read my posts -[an admittedly time-consuming task]- you would know that A) I am trying to set up a localhost using XAMPP on my home computer in order to do the practice websites in the Absolute Beginners Guide; and B) I indeed have little/no experience with internet/server software.

You go on to say:

----quote

Why is it Joomla's responsibility to educate webmaster on things that should already know?

----

From this and the rest of your post, I gather that you are of the camp that thinks that people should learn all about the involved technologies on their own.

There are other people in the collective Joomla! project who apparently feel that Joomla! should be accessible to everyone including absolute beginners. They not only think that Joomla! should be accessible to everyone. They think that it IS accessible to everyone. I know differently.

Brad, If you think that people should quit whining and just become fluent in the technologies like you did, -you are absolutely entitled to that opinion.

In fact I think it might just be the correct opinion. I am on the fence as to whether or not a beginner could ever hope to install, administer, and fully use a complex, advanced system such as Joomla! (or any CMS).

I realize this is an open source, collaborative prject. But a consensus needs to be reached. There needs to be a vote, where the members of the Joomla! community decide whether they are going to cater to the absolute beginner, and continue to present Joomla! as being do-able by a novice. Or, whether they are going make their official stance be: “Listen, you are realistically going to have to do a lot of independent learning here and at least develop an intermediate-level fluency with the systems involved.” -and then TAKE DOWN all the feel-good, beginner-inviting stuff thats prominently displayed on the Joomla website. (in the pages that I cite in my above posts)

Alternately, you all could just go on pretending that everything's hunky-dory. But I think you are collectively doing beginners a disservice. Like I say in my above posts: I might have just stuck with my original choice of Kompozer if there hadn't been all that encouraging text on the Joomla! website. It would have you believe that anyone who can send an email will be creating magnificent websites with Joomla! in no time.

As for the rest of your post Brad: Yes I am indeed wasting a lot of my time as I wait for someone to tell me how to fix the red entries in my pre-installation check. On a positive note, I am somewhat enjoying this 'ranting' and venting. I noticed that in your signature you have a Seinfeld quote. There is a Seinfeld reference in one of my above posts that you might enjoy. If your eyes can stand reading the posts, you might even agree with some of the things I say.

I hope this post is easier for eveyone to read. I do apologize for the 'double paragraph spacing' in my other posts, and the other 'techniques' that I may have employed. [the technique is bad writing?]

Brad, you may be the only person giving it to me straight here.

I specifically would like to hear your opinion on all the feel-good encouraging stuff on the Joomla! website. In your opinion is it accurate? Should it be changed? toned down? taken off?

What is your understanding of how absolute-beginner-friendly Joomla! is, and how beginner-friendly a CMS such as Joomla could possibly hope to be?

- - -
as for my personal situation:

Brad, do you think anyone is going to help me through the installation processs? Or should I just give up? Is this stuff just too hard for a beginner to the world of website creation?


On a final note I will admit that my disappointment and frustration is largely my own fault. I have encountered software before that was made out to be a walk in the park, and it turned out not to be. 'Fool me twice, shame on me' -right? If I really sat down and thought about it, how could a complex and powerful computer software system such a CMS be easy to learn by a beginner? But, I will honestly say that I was hoping that the stuff on the Joomla! website would turn out to be true. Also, one guide that I read [Learn Joomla! 1.5 Fast] said that if you start the guide this morning, you will be creating great websites by tomorrow evening.

In my enthusiasm to make great websites, I guess I wanted to believe these things.

Ask specific questions in a succinct and concise manner, without the insults, sarcasm and 10 paragraphs of useless asides and people will most likely be more than willing to help you.

_________________
Co-author of the Official Joomla! Book http://officialjoomlabook.com
Marpo Multimedia http://marpomultimedia.com

[sarcasm-free post]

Hi Jenny,

There's two levels to this thread. One is my own installation attempt and the difficulties I'm having. The other is a big-picture, fundamental questioning of whether or not an absolute beginner can install and use Joomla! without being hand-led through every other little step. The question that I am asking is do you all think that the aforementioned beginner-encouraging text on the Joomla! website and many of its guides should remain as it is, -projecting its (in my opinion) not-exactly-true message, and getting people's hopes up?

As for the personal level of this thread: I kind of thought by now someone would have offered some help with my personal installation. But as you and Brad commented on, my posts are sarcasitc, long, and poorly written. So I understand if people were too offended to want to help me.

As for the big-picture constructive critism level of this thread: I pointed out a lot of things and nobody discussed most of them. This is a feedback sub-forum after all. There was some discussion, mostly by Chris, but there are many things in my (admittedly long, sarcastic) posts that are yet to be addressed.

I assumed you all would want to know people's true reactions/thoughts during their experience with your website. If someone takes a lot of time to vent their frustrations, this should indicate how strongly they feel about it. It might also be indicative of many other people's disappointing experiences. But these people didn't take the time to let you know what they think. Maybe they're too busy, maybe they just moved on to some other software, maybe they went to the library and checked out a dozen books on PHP, MySQL, etc and taught themselves.

I've had trouble reading ever since I was young. Otherwise I might have gone the self-educating route as mentioned by you and Brad. This is one reason my experience with Joomla! was such a maddening disappointment. I read all that stuff on the website and thought "Wow, I can apparently learn this powerful web creation system very easily. What a relief. If I had to read a bunch of textbooks I'd probably never make it. But this sounds great!" So you can maybe understand my questioning of the website's message to beginners.

I want to point out that my post in the Installation sub-forum contained no sarcasm, nor was it long. It fell to page two. I realized that the orignial title no longer applied and was probably throwing people off so I made a new aptly-titled post. I made a few other posts on other [non-Joomla!] forums and haven't got much response at all. (for what its worth if anything)

If anyone would like to discuss anything in any of my posts, I promise to not be sarcastic and to keep it under ten pages.

Brad, I'd still like to hear your thoughts on the above post.

I'd like to close by saying that its good to express one's anger. To take a line from Loyd Brawn in the tv show Seinfeld: (if) Serenity now, insanity later.

Thanks for reading.

If it is a maddening disappointment I suggest you move on, or roll up your sleeves and fix what is lacking. This forum is not an avenue for expressing one's anger, or to be insulting to others. Please see the rules link located at the top of each page. If you feel you cannot take part in this forum in a considerate and constructive way, then I really do suggest that you move on.

Thanks for reading.

_________________
Co-author of the Official Joomla! Book http://officialjoomlabook.com
Marpo Multimedia http://marpomultimedia.com

Jenny,

Once again you've made a post and talked mostly about me, mentioning little or nothing about Joomla! or its website. My last post was perfectly civil. You could have a little empathy. If you don't want to respond to any of the many points I made in this thread, I suggest that you stop visiting it. Some people just aren't cut out for taking uninhibited criticism.

Like I said in the above post, my defiiciencies aren't the concern here. The deficiencies of the Joomla! website are the main concern here. Its message to beginners is my main beef. There are also other issues mentioned above.

Nobody's forcing you or anyone to respond to the issues I've laid out in this thread. I don't see you listed as a moderator for this sub-forum, but maybe this is your department and you're just not a moderator. So I tell you what; if Chris, and you, and "ianmac", and any other thin-skinned Joomla! team members don't want to respond to the issues in this thread- Why don't you just remove this thread from the forum? It would be easier for you than actually addressing the concerns.

Topic locked

_________________
Regards, Dave
http://www.kiwaniswest.org
http://www.huelsmann.us