Page 1 of 3

Better Module Documentation In The Forge

Posted: Sun Dec 12, 2010 11:05 pm
by jeverd01
Am I missing something, is there a list of smarty variables used by each module? It seems the documentation is really hard to follow, next to non-existent in some modules. I am looking at this from the point I have worked with procedual php code mainly, along with Java. I understand the syntax of PHP object oriented code, the reasons and benefits of using object oriented code, but it seems insane how little of documentation there is in modules regarding smarty tags. Combine this with the fact smarty is already strange it is starting to make me feel like I have my hands tied behind my back.

Also From my stand point I think the forge needs some type of overhaul, and if it occurred it could boost cmsms success ten fold. It seems disorganized, there are no previews of modules, you have to install to even test them. The alphabetically organization is lacking substance, wouldn't categories make more sense? Also a rating system would be awesome.

On a side note CMSMS is absolutely the best system I have worked with, not trying to bash here just offering suggestions.

Re: Better Module Documentation In The Forge

Posted: Sun Dec 12, 2010 11:13 pm
by uniqu3
Hi jeverd01,

you are absolutely right about documentation, but i think regarding Smarty it's best you take a look here http://www.smarty.net/docsv2/en/.

Re: Better Module Documentation In The Forge

Posted: Tue Dec 14, 2010 3:02 am
by tyman00
The unfortunate problem with the forge documentation is it's a monumental task because the module developers do documentation at their own free will. There have been dozens of comments from people about the forge and that it needs to be fixed... the problem is not one person has followed through with it. Why? Because it's not so cut and dry.

I'd like for many features and better organization because I think it would help the system that much more too. But having put a lot of thought into the process it would be extremely difficult to do so for just a few individuals. It could be a full time job.

If you view the help for the modules in the admin they will hopefully help you a little more.

Re: Better Module Documentation In The Forge

Posted: Tue Dec 14, 2010 3:38 am
by Wishbone
What I find frustrating is that many of the modules' descriptions don't describe well what it even does. What I've been doing is check out the module's help in the Module Manager before installing, and test it out on a side install before installing it on a live site.

It would be nice if the modules were organized into categories like on Hotscripts

Re: Better Module Documentation In The Forge

Posted: Tue Dec 14, 2010 5:21 am
by HansDampf
There are so many ways to organize modules. And the way it is done here is one of the most unlucky unfortunately

Have a look at wordpress.org

1) plugins and themes must follow rules to be published there, so a minimum of quality is guaranteed

2) There is not ONE plugin which has 0 files (and in my opinion this would be the easiest fix here, just a simple query whether there are files or not ... )

3) all items are categorized or tagged in a way

4) all items show description, screenshots are possible, a FAQ with the most common questions, installation tutorial, and at the right side the info about compatibility with different versions

5) users can rate the items and there is kind of "forum" for each of the items

... and so on

I remember that there were categories for modules in the modules repository once but for unknown reasons they are gone.

The classification as "stale" for "older" items seems kind of helpless for me

- stale is no common and international understandable word, it is some kind of metaphoric adjective  without any useful information
- it is not IT slang
- if you are able to tag items with "stale" why not remove "empty modules" by using a query?

I can't remember that there were calls for cooperation, for support, for quality checks here in the forum, and I think there is a lot of goodwill here

but as I learned, "do it yourself" is a standard answer, but where is "join the team"? I learned in the last time lurking in the forum that good wiill and engagement is not valued here (see what happens in the german forum ... nearly all moderators are kicked out and are blocked from their "own" projects...)

In my view the problem is not the amount of work, therefor we have databases and SQL ... it is the way of thinking of the powers that be (in their infinite wisdom)

just my 5 cents ;=)

Re: Better Module Documentation In The Forge

Posted: Tue Dec 14, 2010 7:03 am
by Dr.CSS
This has been hashed over many times before, and it's the same old thing, not enough people with the free time to work on it...

The forge is not the same as a web page or a forum or wiki, it is a completely different animal...

BTW, stale means like an old clove of garlic, it's not moldy but it's not the freshest and no guarantee it will taste good (work right)... ;)

Re: Better Module Documentation In The Forge

Posted: Tue Dec 14, 2010 7:30 am
by Wishbone
Dr.CSS wrote: This has been hashed over many times before, and it's the same old thing, not enough people with the free time to work on it...
If the forge software supports categories, I'll volunteer to categorize them.

Re: Better Module Documentation In The Forge

Posted: Tue Dec 14, 2010 8:55 am
by uniqu3
I volunteer for the job with Wishbone ;)

Re: Better Module Documentation In The Forge

Posted: Tue Dec 14, 2010 11:54 am
by Jos
We know the Forge doesn't support categories right now, but I wonder... what is wrong with the project-tags system? Maybe that just needs some cleanup?

Re: Better Module Documentation In The Forge

Posted: Tue Dec 14, 2010 12:33 pm
by uniqu3
@Jos

The problem is thats it's hard to find right Modules to use, not everyone knows that some modules work together with others or uses ModuleManager to find out dependencies.
Also not everyone knows what Module has what name, ok Gallery module says enough with it's name, but not all modules are named like that.

Just short example, someone comes to forge an wants to use eCommerce suite, goes and downloads Products module, now all you see in the forge is:
An alternative to the cataloger module, this module allows maintaining a product database, along with prices, images, and various other attributes. It also has 'add to cart' and 'checkout' functionality
Nobody knows that you need CGExtensions for it, or that CGECommerceBase or that you need Cart  Module and so on.
For first time user this can be a headache Job finding out what comes with what  :)

Re: Better Module Documentation In The Forge

Posted: Tue Dec 14, 2010 12:49 pm
by HansDampf
Jos wrote: We know the Forge doesn't support categories right now, but I wonder... what is wrong with the project-tags system? Maybe that just needs some cleanup?
The project tag is useless, as it is not available at the download-page:
http://dev.cmsmadesimple.org/project/list/module

I do not understand why nobody noticed that! You have to search first for a keyword, let's say "video", than get a list of modules with that tag "video" (or maybe just the word, I do not know), and than you click on the first prominent one and that is empty ;=((((((

Re: Better Module Documentation In The Forge

Posted: Tue Dec 14, 2010 4:13 pm
by Jos
@uniqu3: I understand, but it's the choice of the developer to make it that complicated ;) But I was more refering to the categorization, not about the project-description or module-help.

@HansDampf: http://dev.cmsmadesimple.org/project/list/module doesn't show the project tags, but the main page of the Forge does: http://dev.cmsmadesimple.org/

And when you click on eCommerce you get a nice list of modules: http://dev.cmsmadesimple.org/project/li ... /eCommerce

It's only that the list of different tags is too long and many modules are not properly tagged. But the system is there to use.

I agree that it would be better if the no-files modules could be hidden.

Re: Better Module Documentation In The Forge

Posted: Tue Dec 14, 2010 5:14 pm
by Wishbone
Jos wrote: http://dev.cmsmadesimple.org/project/list/module doesn't show the project tags, but the main page of the Forge does: http://dev.cmsmadesimple.org/
Thanks! That does make it easier. It could probably be condensed better.

Re: Better Module Documentation In The Forge

Posted: Tue Dec 14, 2010 6:19 pm
by Coldman
Dr.CSS wrote: This has been hashed over many times before, and it's the same old thing, not enough people with the free time to work on it...
What people are we talking about? Dev team?
I have never seen an announcement about finding volunteers.
Correct me if I'm wrong.

Re: Better Module Documentation In The Forge

Posted: Tue Dec 14, 2010 6:22 pm
by Dr.CSS
Yes it would have to be a Dev. team member as I said the forge is quite different than other set ups, sorry...