Thread

This is exactly the point. If you step back and put yourself in the place of EllisLab for a few minutes and consider how you would provide the various resources you’ll quickly get a giant headache.

We have:

1. An international audience. People from the US, Europe, Africa, Russia, China, Japan, you name the country, there is a group of EE users whose English and familiarity with English (specifically United States English) varies dramatically.

2. A diverse skill set. We have people who write code from any language one handed with their eyes closed, playing the piano with the other hand. We have people who just barely understand HTML. We have people who routinely launch websites for Fortune 500 companies and people thrust into creating a website for a non-profit (brave souls those) who have never built a website.

3. Baggage. To add to the skill set issue we have people coming with baggage loads of expectations and assumptions. Some people show up thinking EE is “Advanced Wordpress” or “MovableType +” or “EllisLab’s take on Drupal”. EE is none of those things. While certain feature commonalities and language tie most CMS/blog tools together EE is typically very different in approach from most systems. People see weblog or template or theme and that ushers in a whole set of assumptions, most of which will be wrong in some form.

4. Learning styles - You can literally get a Ph.D to try and figure out the different ways people learn. Just for example, there are some in this thread who are against the “shotgun” approach of the KB and wiki. But there are just as many who value that approach, look for it, need it. Some people learn through videos, others through step-by-step examples, others through more of a “dictionary” style lookup, etc…

Its a worthy challenge and one that we do our best to meet. We think the strategy employed has worked extremely well and we don’t intend to divate from it. But we do intend to build on it.

Our strategy is really simple and proven itself very effective. We listen to feedback and adjust resources as necessary; create and maintain a professional environment where people help each other out. That’s our strategy in its entirety.

The first part of the strategy is the most difficult and time intensive so it happens less frequently.

The 2nd part is ongoing all the time. That’s one of the reasons we can be a little militant upfront about how criticism and negative feedback are given. Its not that we don’t want to hear the bad (we do) but when its people yelling or just being snide/cynical its counter-productive to the community as a whole and discourages people from participating.

So a big thank you to everyone who has (and continues) to take the time to articulate what they don’t like and what they do like. And a big thank to everyone who contributes back and helps fill in the learning gaps, point others to new resources, and answer questions. Its immensely helpful, inspiring, and keeps us improving.

While certain feature commonalities and language tie most CMS/blog tools together EE is typically very different in approach from most systems. People see weblog or template or theme and that ushers in a whole set of assumptions, most of which will be wrong in some form.

Perhaps a small step toward solving that problem would be changing the main module’s name to something other than “weblog.” Seriously. What I’m doing has nothing to do with weblogs (though we will eventually have one on the site), and though I’ve changed the control panel to use “section,” I’m still faced with the word all over the documentation and in every template. Seeing the word so prominent in the docs nearly put me off until I realized it was (correct me if I’m wrong) a holdover from earlier incarnations.

Thanks,
Nathan

Perhaps a small step toward solving that problem would be changing the main module’s name to something other than “weblog.” Seriously.

We’ve publicly stated that 2.0 will not use the term “weblog” in the same way anymore. Its a word that served us well when EE was introduced but the time has come to let it go 😊

walpow - It is a holdover. It’s been a concern for a lot of us that don’t do blogs and many of us have expressed ourselves like you. But, the reality is, it’s only us, the developers, that really have to adjust to this “one” word. Our clients, authors, etc. never need to even see the word, it’s a back-end thing. At first, it does throw one off a bit. If I recall correctly, EE-2 will change some of this or offers other options. Edit-Add: Leslie confirms (above).

We’ve publicly stated that 2.0 will not use the term “weblog” in the same way anymore. Its a word that served us well when EE was introduced but the time has come to let it go

Excellent. Perhaps a memorial service is in order.

N

This is exactly the point. If you step back and put yourself in the place of EllisLab for a few minutes and consider how you would provide the various resources you’ll quickly get a giant headache.

Not at all. I would provide a single comprehensive documentation resource that explains every feature of the software (at present some elements are not covered at all) and a section of step-by-step tutorials that cover the basics - installation, setting up member groups, applying a new theme, etc. New users could work their way through the tutorials to create a finished site and custom features could be created by referencing the main documentation.

At the moment the information is scattered across too many different sections - documentation, wiki’s, blogs, forums, knowledge watsits etc. which means new users have to hunt about to find the information the need to do the most basic things, such as applying their own custom theme. I’m a seasoned website designer and developer but it took me days to find out how to do this.

Regardless of a new users skill level, this information needs to be easily accessed, and at the moment this is not the case.

Well I’m glad you’ve figured it out. 😊

Edit: Meaning, I’m happy you finally got the info you were looking for.  I wasn’t being snide.

Well I’m glad you’ve figured it out.

Thanks 😊

Most technical documentation comes in two parts: references and tutorials. I can’t fault EE’s documentation as a reference. I does have some tutorials and samples sprinkled throughout, but this isn’t going to satisfy everybody. Having said that, I’m not in favor of adding more tutorials to the main documentation, because it diminishes its value as a concise reference. It would make a lot more sense to expand on the tutorials that Lisa, Mike, and others provided…

In any case, with the impending release of EE 2.0, I’m happy to take a wait and see approach until I have the documentation for the new version in hand.

The planned changes are specific to the “starting out” experience, the initial context that the basics are learned in, and changing how the available resources are introduced and linked. Once you have the basics figured out the docs become a valuable reference guide much like Markus states. The hope is to better meet the needs of people like Familychoice without interfering with the usefulness that experienced vets like Markus need.

Edit: And then of course you have to factor in that 99% of people ignore the docs anyway! lol. That’s a totally true statistic in the sense that its a statistic I made up.

And then of course you have to factor in that 99% of people ignore the docs anyway! lol. That’s a totally true statistic in the sense that its a statistic I made up

A little high but all you have to do is follow the forums for a while to see some truth in that.

😉

The planned changes are specific to the “starting out” experience, the initial context that the basics are learned in, and changing how the available resources are introduced and linked. Once you have the basics figured out the docs become a valuable reference guide much like Markus states. The hope is to better meet the needs of people like Familychoice without interfering with the usefulness that experienced vets like Markus need.

I still think you have too many options - it’s very confusing for a new customer. If you’re saying that you’re just going to add more content to what’s already there, and make more links between them then this won’t solve the problem.

A good set of tutorials will help people like me to run through the software and become familiar with the way it works and the terminology involved, before hitting the in-depth documentation if more customisation is required.

Edit: And then of course you have to factor in that 99% of people ignore the docs anyway!

Or give up because they can’t find what they’re looking for and end up hitting the forum instead.

And with that, I think this discussion has run its course. Thanks for the feedback everyone. Thread closed.