Incidentally, before someone comes along and says instruction on modules is in the users guide, let me say, I'm away of that. But these instructions have one fatal flaw: they don't tell you what a module is! So, the new user sees it and to him it has no meaning at all. That's insane.

There's a science to giving instructions/teaching. First, you tell the student what the thing is and what it does. Why assume he knows this?

Also, the process of using modules and blocks, sections, headlines, etc. Needs to be discussed in a organized way. It's insane to expect the new user to come here and figure this out on his own -- and if it's all explained in the forum archives, why isn't this explanation in the users guide? Why make the new user search for it?

Right now, I'm trying to figure out how to get an article on the front page. Sure, this is as easy as pie to you, but I've tried several things and it's not displaying. I'll probably have it figured out in the next 15 minutes, but meanwhile I'm thinking: where's the operating instructions?

Imagine someone giving you a brand new video cam without instructions. Imagine further that it's a very advance model. Now tell me you wouldn't be pissed that the thing didn't come with operating instructions?

Well, in a nutshell, that's the problem with xoops: no operating instructions.

Ricland - I happen to agree with the main thread of what you are saying. IE that this is a good system, which is sadly lacking in the documentation side.

I know that it is something being worked on, and recently certain modules have started arriving with excellent documentation.

Anyway - lets see if I can help in my humble way with this particular problem of your... but please remember i'm only an ordinary user as well (and I get stuck quite often also! :))

Text - front page - do you want it to remain static?
Sort of a "Introduction to site" piece?
Or any sort of function?

ricland, please don't call me "my friend". That's condescending, and I am not your friend.

While some of the points you made are valid, the manner in which you expressed them, starting from your very first post, is not one that would encourage people to give you assistance.

Quote:

Ok, pal, let's get started...

Istall:

Current install is Good, smoothest around.

Needed: New users manual that breaks down install into step by step process. This same step by step process will be used throughout new XOOPS tutorial/how-to. New users become familar with it.

Add Commentary: I've seen this somewhere before. Under the instructions is commentary by other users, ie: tips and tricks.

Current users manual:

Terrible. Describing the components is not the same thing as teaching the user how to use them (or what they are used for). The module instructions in the user guide are a good example of this. These instructions mean nothing to the newbie because he doesn't know what a module is.

Needed: Thorough discussion of all XOOPS components in a illustrative, step by step process. Graphics should be used to illustrate admin section. Examples should be given to show how to do things such as intalling a module. The relationship between modules and blocks should be discussed. Likewise, Themes, templates.

In sum, this tutorial/how-to should build a working site from the ground up. It should be right there. I should be able to build a working site by following these steps.

Here's a thought: "Xoops for Dummies"

You've seen the "for Dummies" series of books. They're very effective. Why doesn't each developer volunteer to write a section? If this can be done, please do it in the "for Dummies" format -- assume the user knows nothing.

Again, step by step, illustrative examples work the best. Also, commentary -- tips and tricks -- can be added by everyone.

Note: some of this may already be available in the forum archives, if so, use it.

Testing:

A complete dummy should be found. Sorry, I'm not available. This dummy should not be a geek. Your girlfriend should work fine. Give her the zip file, the new manual, and turn her loose.

Note, where she falters. Fix it. Continue. If she can't get a XOOPS site up and running -- a fully functional site -- the manual needs to be fixed ... unless, of course, your girlfriend is a real dummy in which case she should be fixed.

Questions?

Tell you what I'm going to do. If someone can compile all these forum posts that are supposedly in the archive and email them to me, I'll write the manual.

The way I'll do it is, write a chapter. Post it here for review, then re-write it, then go on to the next chapter. The working title will be "Xoops: The Complete User's Guide."

Someone else can do the graphics and screenshots, or if necessary, I'll do that too.

Get back to me on this.

Ricland, we have a documentation team and they are currently working on making the documentation for XOOPS better. But these people are volunteers, no one is getting paid to do any of the work. They have jobs and lives, they do want they can when they have the time. People who come to the boards and start demanding stuff be done for them right away is a turn off for most people. We help because we like to help and want to help, not because it's our job. If you have a good attitude and show respect, others will do the same for you.

Most all of us, me included, had to learn how to create our own XOOPS sites, through trial and error, and reading the forums here and asking questions. Documentation will improve but only when the writers have it completed and are ready. This is not something that can be done overnight.

FFS, I leave the country for 3 days and you blow up my favourite forum

Ricland, you are absolutely correct that the documentation is not entirely intuitive and at times it is rather insider-speaking.

BUT that doesn't give you the right to slack off the entire system, patronize people willing to take the time to help you out OR demand that we "get to work" as if we were a commercial company, working on a product which you pay for.

Since you can use XOOPS for so much, it is hard to do a "what's next" guide, which will actually be more than just superficial.
Expecting that you can just use XOOPS without any extra work to set it up or modify it and say "I want a site like this guy's football site" (which, if you are talking about fantasyref, is one of the best XOOPS Sites, but also one of the most customised around) is futile.

Calling XOOPS insane because theme makers have sites, which are OUTSIDE the control of the XOOPS crew and which require registration before being allowed to download one or two themes is in MY opinion insane.

You seriously need to learn how to speak to people.

I've stayed out of this thread on purpose, and I feel that the tension has lessened a bit for me to make my point without adding more fuel to the fire

Ric, I agree with your point of documentation. And there are many people spending some parts of their time, knowledge and energy on this issue, as we speak... erhm.. type. As you say yourself, it's not exactly a lack of documentation, more a lack of organisation of the available content. This is the issue we're trying to solve with the documentation team. I'd like to use this opportunity to ask you to join that documentation team, and see how they're trying to organise the available content, and add your ebergy (which seems to be substantial) to their own, so we can all make a concentrated and focussed effort at tackeling this issue.

I would also like to make a few points about the complexities of documentation. First of all, there are many many types of users. There is the script kiddie, the open source ethusiast, the webdevelopers, the designers, the self-tauhgt webimplementors, the internet newbies, and these are just a few of the types of people we have to cater with documentation. The next layer of complexity is the types of websites. There are the default implementations, the customisations, the third party modules, the hacks, the themes, the communities, magazines, blog sites, galleries, corporate sites, development forges.... They all have different approaches on how to set up and customise a site. All have different priorities. Then there is that simple yet devastating fact that people don't want documentation (ever hear of the much used phrase RTFM? -it's there for a reason), but answers to their questions. I know I do. But my questions aren't the same as yours, because of the language barrier, the background differences, the experience level and because of we're different users with different needs for our sites. Now take all this into account, and write the Table of Contents for you XOOPS User Guide. That alone will be a hell of a job... But, some of our brave souls have taken it upon themselves to do this job.

Again, I invite you to join the documentation team and add your energy and enthousiasm to this major operation!

Herko

Now I understand why there's no manual: you guys keep spend all your time making excuses about why one isn't needed, or alternately, why it takes 25 XOOPS developers locked in a room for six months to do it.

Give me a break.

Writing a manual isn't rocket science. Provide me with the raw data and I'll write the manual for you, in a week. Compile all those posts you say are in the archive and email them to me, section by section.

The bottom line here, of course, is you guys are running away from writing a real manual the way Dracula runs from the morning sun. Geeks hate to write, that's nothing new. And as we see here they're ingenious at making up excuses for not writing ...

Well, some are ingenious -- saying there's no need for a manual because all the answers are in the forum archive, isn't ingenious at all.

Give me the data I need and I'll knock off a chapter a day. By the end of the week, you'll have your Tutorial/manual.

Either that or this time next year you'll still be making excuses and I'll still be calling you slackers.

Now quit feeling sorry for yourselves and email me the data so I can get to work.

ricland

It seems you have made up your mind about us, and there is no way we can change that. We're not running away from documentation, although I must admit this used to be the case and still is the case for a large part of the developer documentation. But user docs -no. It's very easy to discard all the work the docs team is doing and saying you'll do it all yourself. If you're so great, then you should have been able to understand XOOPS's trappings and inner workings easily. What it comes down to is the quality standard we uphold, and if you don't feel up to that, then fine.

It seems you are bent on doing it all by yourself, and you're free to do so. But don't demand any help from us if you're not willing to join the team. So stop offending people here and do what you feel is best. But don't bother us with your petty opinions about our motivations and work again.

Herko