Peekay raised some good points about the documentation, but this needs a new thread in the Documentation forum, so here it is:

Quote:

Well, I've published a tutorial on how to convert a standard module to a ModuleAdmin GUI (it needs to be updated, as things changed in the meantime), but there is also this excellent documentation from Mage

And several developers updated already their modules to that GUI (John Mordo, Wishcraft, and few others).

As I am updating the modules, I see that main issue is that we don't have good standards/guidelines, and no good library of common functionality. That means that the same feature is being re-implemented in many different ways. That makes maintenance a nightmare.

The Core Team is aware of the need for documentation, and Trabis did already a great job documenting XOOPS 2.6.0 code.

The Core team wants also to work on a common module framework (a combination of XMF from Trabis and RMCommon from BitC3r0) that would make it much easier to develop and update modules.

And there is a "TDMCreate" module that helps with creating new modules. The latest version is 1.38 Beta 1

Quote:

We've been always asking people to help with updating the documentation (e.g. here on Basic Module Pack and here on the Wiki Clean-up), but it's hard to get people

We've got many people volunteering for the Translations, so hopefully, there will be more also helping with the documentation.

There was a good proposal for Documentation that we could follow. We just need people to jump in and say: OK, I'll help with this topic

I hope we can make a call for a "Big Spring Clean-up" and focus on cleaning up and updating the documentation

Let me attempt to put my concern/confusion re: Peekay's comments re: 'inner circle of coders'.

I have been around XOOPS for a while but definitely don't consder myself in the 'inner circle'. I too have frequently found it difficult to contribute due to the lack of adequate documentation, although my frustrations have been more geared towards the core than modules. (A side note: Let me say that the current core team is much more receptive to allowing others to help than I have seen in a long time!)

Modules have typically been the creation of 'lone wolves' who develop a module either as a hobby or out of necessity for their business. There really isn't any quality control on XOOPS modules. Several attempts have been made to 'suggest' coding standards, test to be completed, etc. however there are insufficient mechanisms in place to enforce these suggestions. As a result many individual module developers have developed code using brute force methods (not using XOOPS core APIs) or what they perceive the best method given limited understanding of the XOOPS core - I include myself in this category of developers historically. Industry coding standards and best practices have come a long way since many of these modules were developed.

Ideally the community would like to be able to expect each module developer to develop code and document it to the level required to let less experienced programmers pick up the module and make changes to correct bugs or add enhancements. Ideal, but not reasonable. Many module developers do this as a hobby. Attempting to 'require' all but the rudimentary coding standards in the current environment will just continue to drive away the very programmers we currently need. There are ways to improve the overall code quality and standardization but it will take significant changes in the XOOPS council and community operations.

The problem the community currently faces is that these modules have become de-facto standard add-ons to XOOPS and the original developers in many cases have 'moved on' for various reasons. As the current XOOPS module developers pick up these modules to bring them up to current programming norms, etc. they/we all want to add our expertise to bring these modules up to date. Again, some developers will overhaul the entire module to use XOOPS APIs, some will just 'patch' the changes necessary to get it to limp along in the current version of XOOPS.

Given all of this as a backdrop let me state my real problem/concern as a module developer/maintainer. I have attempted (several times) to document what I am doing to change one of these older modules to current standards to try and be helpful to someone else but truthfully each module's conversion is unique. A few things are required, but not sufficient to guarantee the module will work with the current core, PHP version and/or MySQL version. For example it's relatively straight forward to document some items but other requirements to core APIs are really dependent upon how the original module developer handles the data stored in the database, whether they're using custom classes or classes that are an extension of the XoopsObject. Making these changes are often difficult and not for the faint of heart. So I don't think the 'inner circle of coders' are attempting to prevent others from updating modules it is just that it is very difficult to create a generic 'how-to' document. Some of the changes required (say changing TYPE=ENGINE in the mysql file, or $HTTP_GET_VARS to $_GET) are not XOOPS related. It's not reasonable to ask XOOPS core/module developers to document all the changes in PHP and MySQL that may effect some modules.

Having said that I do believe there are things that can be documented to help both novice and experienced PHP programmers become productive more quickly.
- Any XOOPS core API change needs to be documented (trabis is doing a very good job of this in the 2.6 core).
- A 'how-to' document for each core API change should be created that explains changing a call from the current core API to the new API (if one exists)
- The Development WIKI could be reorganized to provide seperate sections on how to update modules for various versions. Something like:
- Updating a module from XOOPS 2.2 to work with XOOPS 2.3
- Updating a module from XOOPS 2.3 to work with XOOPS 2.4
- Updating a module from XOOPS 2.4 to work with XOOPS 2.5
- Updating a module from XOOPS 2.5 to work with XOOPS 2.6
- etc.
The above API 'how-to' documents could then be placed in the WIKI
- At some point updating the Development WIKI to have a 'best practices' section would also be of value. This would help developers who are new to XOOPS to be able to ramp up quickly.

Maybe all of this should be moved from the xoops.org site to the dev.xoops.org site and really focus xoops.org on using XOOPS, not developing it.

Now the crux of the problem is the lack of developers/documentors. The community is clammoring for new core releases with bug fixes, new features, etc. The few current core developers are unfortunately the ones who really need to develop the documentation so that module developers can have modules that work with updated core releases and incorporate the new features quickly. If this does not occur it leaves each of the module developers to dig through all the new core code, identify the changes and then figure out how it effects the module they're updating. Imagine if PHP or Smarty did this - developers would abandon those platforms in droves... My personal belief is that a new XOOPS core should not be able to go to a BETA status until all the documentation is completed - but of course that is a call that would be very difficult for the council to make...

Jim, as always, you're raising very valid points.

We REALLY need help from the community to start documenting XOOPS modules and Core.

The few people who are working on Core can NOT simply do everything, while we are watching from the sidelines!

Documentation has been always an issue for XOOPS. Can we break the cycle in 2012 and create this year a useful documentation for XOOPS users and developers?

We just need few people who would be willing to to contribute to this task!