Criticism on lack of Documentation

[shawn122]

See attached link concering documentation for Joomla/mambo
http://designorati.com/web-design/edito ... rietary/1/

Here is the introduction:
Question: What happens when programmers go it alone, running their own company, without administrative oversight, a documentation team, or a perspective grounded in the markets served by their product?

Answer: The Joomla! content management system

[Apollo]

The article is full of frustrations. It is ok to me. But writing bullshit like this

Components are applications or plug-ins that operate only on the back-end, in the CMS admin area.

They need to do their home work and rewrite the article.

visit OpenSourceCMS.com, an amazing new site

I guess they just wake up from a very long (winter) sleep. OpenSourceCMS.com is not new.

[iainshaw]

looks to be an article prompted by the recent lengthy and acrimonious thread started by thegent on the Mambo forums.  The article fails to point out thegent is one of the rudest posters you'll come across.

I think the core point is both well made and well understood.  The documentation for both Mambo and Joomla! aren't up to the standard of a professional CMS.  After that the article gets rambling, repititive and error prone. 

Anyway Shawn - what brings you here?  That's a friendly question btw.

[shawn122]

lol...no reason actually
I read the post and figured it concerned both CMS's so decided to post. 

I also saw the quoted 'thegent'....and you are quite right in your assessment.

[stingrey]

Could Documentation for Joomla! be better, absolutely.



So how does this happen?

Simple - people volunteer their time and energy to make it happen:
http://forum.joomla.org/index.php/topic,429.0.html



After all this is Open Source and the only way it works is if people freely give their time to freely help their neighbour.

Everything that Joomla! is, is only possible through the generosity, goodwill and freely given time of thousands of individuals throughout the world, who are proud to be part of the Joomla! family.

[visionspin]

This was very upsetting...we are doing the best we can. Instead of criticizing, how about offering to help or to find people willing to help us? One reason that the documentation is not fully updated is that the new 1.5 uses new terminology, etc. and we needed to wait to see what it would be before fully updating the manuals.

Also, when I go into the Help section, I see a number of manuals...admin, developer, installation, etc. and so am not sure where this person is getting that we have "no documentation".  Is it just because I am a doc team member that these things appear there and they are not visible to non-doc team members?

[bpd1069]

Comment:
To illustrate the frustration many newcomers have with the documentation you must switch your point of view to one who actually needs to refer to documentation.  As creators and maintainers of the Joomla CMS it is natural to assume that this would be the place to find Helpful and authoritive docs.

For Example:
The installation manual assumes the configuration of the server is fine, there is nothing, not a link, not a note, for when things are not 'perfect'.  According the the 'Easy Way' all you need to do is fill in a few forms and presto, all done.  Is this intentionally misleading? Not sure, but new users should not have to scour the internet to find how to do this. 

Much of the documentation appears to be just quick copy&paste from other posts.  This is fine for me, but when you post shell commands with obvious typos I think it will lead to more confusion and frustration rather than helping.  After all you must see if from the readers point of view.  They are reading the installation documentation because they need to, and again, who better to write authoritative documentation? 

You may not see it as a big problem, and you may have your eyes on the next version of Joomla.  But rest assured, your doing yourselves a HUGE discredit by not addressing this issue. 

I wish I could assist and help by writing documentation, but since I am one of those people that need to refer to it, I can't.  If and when I do get to the point of finding my way through the process, I am sure that this emotional frustration will not put me in a state to revisit that frustration.

Remember, your first impression is often the most important.

[AmyStephen]

I was mesmerized staring at that devilishly gorgeous man. Did u SEE him? He was all windblown and sheckzy, his coat opened invitingly, hair blowing away from his face, his smile -- those lips -- the hairy lip area, the earring - that rugged brick background. So hot...so manly. So Pariah!

Now, that I am all pumped up and inspired, I think I'll go back to writing my documentation.

[AmyStephen]

Remember, your first impression is often the most important.

Welcome to Joomla! It's not often I get to say Howdy! to someone on their first post!

[bpd1069]

let me make something clear...  I don't know anyone on the Joomla team, but from what I have seen it is a great enabler for those wanting to start a web presense and not have to pay out the nose to keep it updated.

With that said.  A critique can be viewed as a negative or as a positive.  I pointed out two distinct oppertunities that can be expaned in the Documentation in a very specific region, one that arguably is the first point where a lack of documentation can turn someone away from this software.

If you take the critique personally, there is nothing I can do about that.  But the problem remains, getting a CMS up an running is crucial for convincing someone that they should invest their time and energy in this endeavor, thus increasing the base of users.  Isn't that a good thing?

[AmyStephen]

Yes, you are right. We need better documentation. And I think you are trying to be helpful.

But, can I tell you something about your timing that you were simply not aware of.  Those people above you -- they are working their butts off trying to build the documentation. And, this is not a paid position. And, they have jobs and families and lives. So, when they saw the article, they were hurt. And, you piled on.

So, you have to see that your timing was not the best -- and I am certain you did not have any idea about that, so, let's move on from that point.


NOW!!!

You have to admit -- COME ON!!!!! - in light of all of that -- it was FUNNY to have that be your FIRST POST when you were "getting on us" about first impressions.

NOW WAIT!!!!! you don't want us to get defensive, so, show us how -- LAUGH!!! THAT WAS FUNNY!

I hope you hang around - because we are really very good people and eventually, you will be helpful to us in the doc area! We do need good help!

THANKS!!!!!!

[bpd1069]

Witty, yes...

I am sorry if I seemed to be piling it on, but I always try to post in an existing topic that seems relevant. 

About working on a tedious, time consuming project for no pay.  I do research for an activist group fighting for the libery and freedom of citizens of the US.

I am sorry if I don't have a sense of humor anymore.

[AmyStephen]

It's okay; don't worry about it!  I think you are great to come back and keep the conversation going. AND I am MOST especially glad that you are fighting for what seems to be slipping away in terms of our liberties and freedoms.  Thank you for your work in that area!!!!

We are trying -- the longer you are around here, the more you will realize that! Especially the folks above -- they have been at it for years!

Thanks so much for hanging in there with us.

If you want some documentation to get you started, let me recommend It has several very excellent articles that people have found (including myself 6 months ago) very helpful to get rolling.

If you have questions, post on the forum, people are very helpful.  And, if you aren't getting help, feel free to PM me and I will try to help you out - or find you help!!!

Thanks, again!!!!

[bpd1069]

Thank you very much... I will surely be reading the forums and posting questions.  I have a great many websites to build and very little experience so I am sure to be here on a regular basis, after all what better authority for Joomla Documentation?

[AmyStephen]

I think you and me are gonna be real good friends! 

Please keep in touch -- I'll be interested in hearing your progress and I think the way you handle yourself is awesome. You just turned everything around for us. AND, it is MUCH appreciated!

Amy

[AndyF]

Hello all,

So -- as far as first impressions go, here's my take on the situation...

First, I am interested in what a CMS can do and what would be a good one; I run across Joomla! and am excited! Now I'm not sure what exactly it is, or who does what with it, but I have some general ideas... so I look around for a guide or signposts, and I find:

o Some forums with a various suggested links to get started with (which ones are for me?)
o A help area that has administrator and developer manuals (are those what I want?)
o Information in some quantity, but too chaotic to approach easily

What I don't find is any single point of orientation, a "start here" document. I'd want such a document to tell me things like:

o Hi
o What Joomla! is, what you do with it, who does what
o Where do I find other documents and what's in each of them
o What demos, white papers, reviews, and other resources might there be
o What other topic knowledge (CMS, security, design...) is available in the world

Basically a really polite greeting, overview, and index into the world of Joomla! knowledge.

Maybe I will soon find this nice starter document that I envision, but so far I haven't. And maybe other work is more urgent (how many times have I had to make that tradeoff myself!) but as a newcomer this initial guidance would be invaluable.

Looking forward to helping,

Andy

[AmyStephen]

Andy,

I agree completely that organization is really the problem. We have a *ton* of documentation -- what we need is a more intuitive way of laying it out for others. And, there are plans to help move us in that direction. Your bulleted list is really nice (I love this: "Basically a really polite greeting, overview, and index into the world of Joomla! knowledge."; nice!) -- we will use that as input to this process.

Here's the best newcomer's starting point: the "Absolute Beginner's Guide to Joomla!" This is a collection of *excellent* tutorials people have found jump start learning.

Andy - if you have questions, post them to the forum. But, if your question gets "stuck", feel free to PM me and I will help answer the question or find someone who can help.

Thanks for taking time to help us. We look forward to future helping, too!
Amy

[visionspin]

Thanks, Andy!

I appreciate the way you communicated your helpful suggestions...using a polite, caring, understanding tone. Suggestions presented in that way come across as helpful, rather than solely critical.

As Amy said, we are currently working to organize the ton of documentation and your list lays it out in a nice, orderly way. We are making progress, but have only a handful of volunteers to do a huge amount of work. Would you like to help? We could definitely use the perspective of a newer user and an extra pair of eyes to help edit.

[ribisall]

For what it's worth, anyone familiar with open source, really familiar, knows that you have to depend upon those that have come before you, second, and upon yourself first.  Open source software is not design for users that require hand holding.  It's designed to grow like a tree being fed by leaves that are we users.  It's roots cannot grow stronger without the food we feed it.  You can't get that from a commercial package.  Open source is about learning what works and what doesn't and making it better for those that aren't quite ready for it now but will be in a year or 2 years down the line.

I am new to Joomla, only been using it since March 15, but I had my first test version running 10 minutes after installation my live version up in 15 minutes and with no more documentation then the install screens.  I knew going in that I needed AMP on my local machine, I knew that I was using PHP/MYSQL, and knew, just have I had for 20 years of technology testing if it breaks I will find a way.  I can tell you one thing, the first time I open Joomla and saw all the tools, all the options, and all that potential all I could think was, " holy s***, this is going to get me in trouble!"  And I have enjoyed every minute of it.

Because of Joomla, and without documentation and just depending upon what I find in the Joomla community, I have 8 working production Joomlas on my local machine, 4 active sites, and 3 in standby to go live.  I have expanded to play with moodle, smf, and a host of other OS packages learning to get them to work together following the instructions from countless sites.  Just since March 15.  I have built my own templates from scratch, following the instructions of some great tutorials but before that I had dived into the code to 'see' what was going on.  Now, I'm converting HTML files and converting HTML designers who are hot on this project.  I'm actually training newbies, me, a newbie.  As well as starting my own tutorials to share.

The documentation is there, if you want to look for it.  Another post brought up the fact that many newbies just don't want to put in the time to look.  If they have the skill and the will -- they will find a way, if not they will move on, but honestly-- they will be back because before I found Joomla, I had tried typo3 as well as 6 other CMS packages.  Guess what, not even in the same league in terms of usability, community, and DOCUMENTATION.

Centralizing the docs, and putting together a formal book would be great but until then I do Joomla the same way I do everything else, try, break, fix, try some more, and look for the break crumbs left by others.  And I never start on a live site, made that mistake with http://www.ultimateuser.com, it works but now its bloated so I'm redesigning.

This project is great, and it has my full support and where ever possible I will do what I can to aid in better documentations.  So, let the half hearted walk away they'll be back once they try some of the other OS packages.  Nothing runs like a Joomla!  (John Deere will forgive me)  Thanks to the core, I am forever Joomlaing!

[Gare]

Hi. Thought you all may be interested in this:

The current issue of PHP Architect - Volume 5, Issue 3, no date?  reviews Joomla in quite a favorable light.

"Joomla! Big Iron Content Management?" by Peter B. MacIntyre
gives Joomla 4 out of 5 stars.

The deficiencies mentioned were lacking documentation and

"be aware that Joomla is not totally MySQL 5.x -compliant.".

The documentation is certainly lacking, but this is understandable, given the situation that exists in its product life cycle, and its recent splitting off from Mambo.

"Overall this is a great product with a bright future."

[AmyStephen]

@Ribisall -

I met you finally last night when you inspired me the first time! I was looking back through your posts wondering how I missed you and you didn't get my welcome basket of User Guide material I hand out.

You are TOOOO FAST! March 31 was your first post. You spent the first couple of weeks with the real geeks in the installation area. No one in their right mind should accomplish what you have in that short of a period of time!

@Gary

Is that resource online? I would love to see it if you have a link.

Boys -

I love yours posts -- they are so friendly and kind and nice. But, I have to take exception to the claims that we have no documentation. We have documentation coming out of our EARS! We have so much documentation, we have it sitting in boxes in the back bedrooms and in the garage.

This is my welcome wagon piece I hand out  "Absolute Beginner's Guide to Joomla!" This is a collection of *excellent* tutorials.

And TONS more where that came from.

When v 1.5 comes out, Michelle and Shayne(the doc bosses) have wikis full of administrative guides and help screens and development APIS and Torkil's been documenting the E/R diagram for the database and there are "how to build" components and modules and plug-ins....OH MY!!!! I am serious.

It's only been six months since Joomla!'s birth. I can not believe what these folks have done!

Having people like you guys join us is just making our future better and better and better. I am sorry to gush, but, it's been a couple of weeks since I have done so and I am due!

I LOVE Joomla!
Amy

[Entangled]

As a CMS newbie, I find the lack of documentation for a CMS rather odd ...  after all, isn't documentation content?  I am suppose to believe that Joomla will solve all my content management needs, yet it's not even being used to solved it's own content (documentation) management needs ......  hmmmmmmmm, go figure.

Suggestion ...  put all the useful links to documentation, hints or FYIs in all different the forum threads or other sources on ONE static Joomla page so us newbies (ok .... me) don't have to waste a bunch of time searching and scanning the forums.

Thanks Amy for putting together your "welcome wagon" piece.  I have not looked it over yet, but, I will shortly ...  question though.  Why is in a forum where it will slowly disappear and not under the menu option "Help"?  Call me stupid, but, I tend to click on links that say "Help" or "Support" before I click on a link that say "Forums".

[AmyStephen]

I LOVE THE FIRST POST! 

WELCOME TO JOOMLA!

Thanks Amy for putting together your "welcome wagon" piece.  I have not looked it over yet, but, I will shortly ...  question though.  Why is in a forum where it will slowly disappear and not under the menu option "Help"?  Call me stupid, but, I tend to click on links that say "Help" or "Support" before I click on a link that say "Forums".

EXCELLENT points -- we are heading in that direction. Michelle has some remodeling ideas that are in the same area that you are talking about. And, yes, check out the guide -- I just made the list -- but you will not believe the great stuff you are going to find in there!

If you need help, post to the forums, if you get stuck, feel free to PM me and I'll help or find someone smart!

Cheers!
Amy

[Slixter]

Why is in a forum where it will slowly disappear and not under the menu option "Help"?  Call me stupid, but, I tend to click on links that say "Help" or "Support" before I click on a link that say "Forums".

The main menu at the top of this site has that very link that says "Help" which takes you to the Joomla! help site at http://help.joomla.org

Lots of good stuff there. 

--Slixter

[Entangled]

The main menu at the top of this site has that very link that says "Help" which takes you to the Joomla! help site at http://help.joomla.org

Lots of good stuff there. 

--Slixter

Not to be rude, but, no kidding ... how do you think I found this thread to begin with?

My point is/was that Amy took the time to compile a list of useful links and that list should be on the home page of the Help link, not buried within the Documentation Forum/General Documentation (Discussion area for things related to the Official Documentation Project).  Her page, in my opinion, warrants as much Help "credit" has the UFT-8 and Migration from Mambo articles which are the only two "things" I see when I click on the Help button.

Joomla is a tool to get a job done.  I have a job I need to get done, I have no problem doing the "learning process", but, to sit here and scan forums looking for "nuggets of info" on how to initially use or how to generlly modify Joomla (a tool) is totally a waste of time and very frustrating to say the least.  What I have seen (gathered in my short Joomla time here) is that the documentation is out there ... ALL OVER THE PLACE!  Documentation is content ... Joomla is a CMS ...  hmmmmmmmm, am I missing something?  If Joomla cann't be used to manage it's own documentation (content), how well is it going to manage my tera-bytes of content?

I have "played" with Mambo, Joomla and XOOPS ... now back to Joomla to see if I can finally get something productive out of it.  I have no problem going over to Movable Type for $199 (or any other commercial product) if it means I can get my project done quickly, and "unfrustrating" because the product comes with some documentation and some support.

I have worked for some major software companies, and have learned that someone will always complain about documentation ... lack of, poorly written, or not organized correctly, etc, etc.  I for one, hate online documentation because it makes "dog earring" pages for future reference rather hard.

My "where's the doc" rant is done for now.

[AmyStephen]

@Entangled -

It's true -- I think I said above that there are redecorating plans in the works -- right now, the plans are on paper. But, we need to start ripping out walls, etc., and get this in place. Six months since it has begun - over 30,000 registered forum users!  I'm a newbie, too! These folks are amazing! We have to create a good "front door" to greet ppl when they arrive! They don't need much just the basics! We get it! BTW: Slixter is the world's best moderator. If he comes to your question one day -- you are in most excellent hands. And we are SO GLAD to welcome you to Joomla! One newbie to the other -- Joomla! rocks! It is so much fun -- and, now that you have the guides -- your early days will be much, much easier.

Post questions to the forum - get stuck? - PM me - I'll try to help or find someone who can!
Amy

[stimulus]

I love Joomla, and I appreciate all the work everyone has put into it.

BUT. There are serious holes in the documentation. There's plenty of reference material available for more advanced users, and some solid but simple how-to stuff from third parties. That's normal for open source software, and it's fairly common for software in general. It takes time for documentation and usability to get the attention it deserves in commerical software, and in the absence of market factors that help lead to better documentation (ie, too many calls to a company's tech support), open source software is even slower in developing high-quality documentation.

In this article by Jakob Nielsen (a usability guru), he talks about how companies are often initially hostile toward usability. "Developers simply don't want to hear about users or their needs; their only goal is to build features and make them work on the computer. In this mindset, humans are irrelevant -- they're told to use the system, regardless of whether doing so is easy or pleasant." Eventually, companies change to be more successful.

Ribisall's comments sound quite a bit like that to me. "Open source software is not design for users that require hand holding... If they have the skill and the will -- they will find a way, if not they will move on."

I don't have all the answers, but I hope that the Joomla community develops to a point where quality documentation is considered as important as quality code. My questions - which is holding Joomla back more, lack of features or lack of quality documentation? Which would cause more people to start using Joomla?

[AmyStephen]

Stimulus -

EXCELLENT article -- thanks for sharing!!! You will be most pleased to hear that we have just recently evolved past stage one! lol   

The initial stage is characterized by the slogan, "A good user is a dead user."

..which is holding Joomla back more, lack of features or lack of quality documentation? Which would cause more people to start using Joomla?

Excellent point. And, of course, it's a trick question because obviously both are needed and the forum moderators and overarching core group directing activities; funds for continued operation; ; marketing and testing....and the list goes on.

Couple of questions for you -- then, the sign-up sheet for enlistment -- your writing skills are too good to pass up. And, I mean that sincerely.

First of all, why do you seem to assume that there is not a GREAT DEAL of activity underway in this area? Stimulus, you have 21 posts! Unless you are lurking as someone else, you might not quite understand what all of the activities are currently being worked on. There is so much forward movement in the documentation area my head spins. I could not even list for you what all is going to be available in v. 1.5!

This project has been in place for six months! ONLY SIX! I kid you, not!

Given the pending major software improvements coming SOON! , it makes little sense to go back to v. 1.X documentation and beef it up. So, the hours and hours and hours of activity are being focused on v 1.5. And, you do not see much of that. What I am trying to tell you, Stimulus, is that it is easy to miss the work in this area -- but, do not assume, please DO NOT ASSUME that people here are ambivalent or unconcerned with these issues. Because such an assumption would be incorrect!

You wait and see! You are going to FLIP OUT! 

Now, question 2 for you!!! What is wrong with using quality third party documentation? Joomla! is a plug-in device designed to house third-party extensions. Why shouldn't the community also benefit from the fine work in the tutorial area that these people provide?

OK -- I presume you have my welcome wagon gift? "Absolute Beginner's Guide to Joomla!" This is a collection of *excellent* tutorials.

+++++++++

Now, the sign up sheet! Can you help our documentation team? Do you have time to at least help edit some of the major work underway? A wiki? A pdf? A help screen? An api interface? A E/R diagram? An administrator's guide? We are drowning in here!

THANKS honestly HUGE THANKS for your feedback and for the link --- that is an EXCELLENT resource!!!!
Amy

[stimulus]

Amy,
While I haven't written much on the forums, I'm not new to Joomla. A little over a year ago, I moved a non-profit that I'm a member of from an HTML site with an ancient message board system to Mambo. Earlier this year, we moved to Joomla. As far as Joomla sites go, it's got just about everything: 300+ "static" pages, 40,000 message board posts, e-commerce (Zen Cart and eTapestry), 100+ user blogs, event calendar, doctor directory, photo gallery, chat, e-cards, link collection (medical journal articles) and more. I haven't written much on Joomla publicly, but trust me, I've read tons. I administer the site and teach 50+ volunteers how to use it to create content. Joomla is awesome!

I'm actually very curious to know what's going on with documentation for 1.5. I don't know if I want to be a member of the official doc team or if I'll opt to create my own 3rd party stuff. (I have no problem with 3rd party documentation and have found it quite useful. I agree with the other poster, though, who said that it needs to be linked to from the "Help" subsite and not just the forum.) I already write a decent amount of specific how-to stuff for the the non-profit I mentioned. I can definitely edit some material, preferably a PDF, guide, or tutorial of some sort. (I hate the help screens!  ) I'll PM you.

Sorry if I came across as too critical and way too quick to make assumptions. I love Joomla, but for it to really meet its goals, the documentation (official or 3rd party) does have to be more complete. I'm hoping that'll be the case in 1.5.

[AmyStephen]

I already write a decent amount of specific how-to stuff for the the non-profit I mentioned. I can definitely edit some material, preferably a PDF, guide, or tutorial of some sort. (I hate the help screens!  ) I'll PM you.

Sorry if I came across as too critical and way too quick to make assumptions. I love Joomla, but for it to really meet its goals, the documentation (official or 3rd party) does have to be more complete. I'm hoping that'll be the case in 1.5.

No - you did NOT sound too critical! Very good stuff. We need a billboard, too, , to post what is underway. I think many people simply assume "what you see is what you get" and that is simply not the case.

Also, it's tough to tell if someone is new -- I am obviously new and not from the Mambo crowd. Your nic might be familiar to others and they would have known better than to offer you the welcome basket.

NICE website. Very elegant. Love the colors.

I think you would be good to help with Michelle's "help page" plans and third party documentation. You should PM "Michelle Bisson" -- she's the one in charge and can hook you up!

Sorry if I came across to strong - my passion can be misread  I only wanted to clear some things up, that's all! 

THANKS for your feedback and it's good to have you onboard here at Joomla!
Amy

Edit: End Edit.