Modules should NOT be published on drupal.org until they meet a minimum documentation requirement, there are a number of modules which clearly fail this such as the panels_taxonomy module.
As far as i can see, there are no requirements for documentation when submitting a new module/project.
A number of modules have extremely poor or no documentation, this gives the impression that
- drupal project is a bit unorganised
- contributed modules are unlikely to be documented
- users are not sure if they are using the modules for their intended use
- module developers are not sure about how a module should work and are less likely to take it up for upgrades
on the bigger picture, this could lead to long term issues that many other opensource projects have such as
- developers knowing it all while people who are starting have an extremely hard time getting a foot-in
- less chance of a module being maintained by another person
- greater chance of a module falling out of maintenance and not making it into the next release version
- more modules that "come and go", many people will have issues upgrading where modules are not maintained due to the previous reasons
I propose a two prong attack..
- A set of guidelines drawn up for the minimum requirement of documentation a module needs to have before it can be published, this doesnt have to be over the top and and include things like screenshots etc, but just basic good advice such as, what the module does, how it does it (from the code perspective), a brief step by step tutorial on getting the required functionality from the module
- existing modules have the ability to be flagged as not meeting this criteria, email is sent to the owner stating they need to resolve this
- any new module must meet this criteria before being published on the drupal site, this is just a quick testing process and could be part of the publishing workflow, i think you will find a number of people who would volunteer here (i would!)
i'de like to see some discussion and action from here