Modules should NOT be published on 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

second part

- 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




suzanne.aldrich’s picture

How about two tiers of modules - the more usable modules, and the ones that are just plunked up there? If there were standards to strive for, it would encourage module developers to write some documentation and have better interfaces, and I think it would really cut down on the flood of support requests.

dgtlmoon’s picture

webchick’s picture

I support writing up some recommendations for module authors to follow and linking to it from the project creation screen. But I don't support placing barriers up in front of people who are trying to contribute... and I say this as a huge supporter of and contributor to Drupal's documentation efforts.

If you want to see action, take the first step in writing up such recommendations.

dgtlmoon’s picture

The barrier is pretty small, maybe you have to turn a handle instead of just pushing a door.

Im adverse to this opensource attitude that if it's broke - you fix it

I don't know the right answers to this, but what I do know is that its a bit of a problem and would be great if we could work in a way where even some very minimal documentation is required

dman’s picture

I'm seriously behind the idea, and agree that the majority of modules are woefully undocumented. I'm not sure about the enforcement angle ... especially as it requires an audit of some type.
But a few minumum requirements - similar to the code standards requirements - would be fair.

  • First, all but the most simple modules should publish a help page - even if it's simply a verbatim inline dump of their readme (which is my usual approach) . This feature could easily be in core as a default.
  • Second. The README (and/or help page) should list the new published pages/menu paths the module provides.
    I am so sick of installing a module, then poking through all my old menu tree trying to guess which new item with a similar name has been added. This is exceptionally bad for modules that provide 'local item' tabs which don't show up as menu items, but silently appear somewhere mysterious.
    The administer-by-module tab helps a little, but not enough - in taxonomy_image for example, it does NOT show the actual, active, new page where the action happens, just a link to the settings. There is a similar problem for context-menu items. Even core taxonomy.module doesn't have a direct reference to its 'taxonomy/term/n' paths in its installed docs.
    So, nowadays, whenever I install a new module, I just open up the code and inspect its hook_menu implimentation, then go visit the pages to see what it does! How to see what it does should not be such a hard thing to find!
  • Also, many modules now do their bit by adding functionality via FormAPI. This is great, but a help note explaining WHICH forms are now altered would help. If it's silently added a collapsed fieldset to certain node edit forms, you could spend ages looking for it. Documentation should, at minimum, say where to look to see the change. They should be PROUD of what they do.
  • There should be a lot more cross-referencing between the module action page and its setting page. (and help page) Instead, these locations are often 3 or 4 clicks away from each other! Using the hook_help method to add a paragraph at the top of related pages may help.
    Even core could benefit a bit from this, a link from admin/build/themes/settings to admin/content/node-settings (and vice versa) for example may halve the number of FAQs about "how to remove the posting name and date" from displays.
    Inline, Context-sensitive cross-referencing is probably better documentation than any number of paragraphs in a third text document explaining how to get from A to B. The concept is called hypertext.
  • Possibly a different issue, I'm sure it's been brought up elsewhere, but the project group names that module publishers come up with seem totally arbitrary and unregulated. My modules page is a mess, as I can't even sort alphabetically now that each module is in its own boxed group.
    I realize this is an organically created problem, but can't we recommend that the existing modules classifications get used where possible?
    I see usable labelling of your module as being part of 'documentation'
  • DOXYGEN internal documentation is sorta OK. Although it seems verbose sometimes, it does pay off in larger projects. Like this. The Drupal API documentation module actually works, but if it were integrated over top of the contrib directory as a browsable API like already happens with core api.drupal , then module code documentation might actually get more airtime. More airtime means more visibility and hopefull more care going into making GOOD documentation.
    Axel kollmorgen maintained an external mirror that did just that ... for a while. It seems the contrib section has been culled. Probably due to space. :(

Personally, I don't care about long change history notes in a README, but they are often more prolific than the real "what this module does and how to use it" instructions I'm looking for there. Why do folk spend more time documenting their mistakes (bugfixes) than the successful, possibly hidden features that make up the bulk of code?

I'd love to see extended userguide / walkthroughs and site recipes distributed with some modules, although that's obviously out-of-scope to this issue. I'd also like to see an HTML-integrated way of publishing docs that is a bit nicer to work with than a README. But, also a bigger idea and off-topic here. IF however, the hook_help() was a bit more user-friendly to module developers, it might get used better and more.

Sorry, this turned into a wishlist/rant. Just throwing some ideas out there towards what I see as a 'minimum standard'

webchick’s picture

I'm adverse to this opensource attitude that if it's broke - you fix it

Really? If you don't help fix it, who do you suppose should? There are no magical documentation fairies. :) It's "regular" people who figure things out and contribute back what they learn.

You can argue that the maintainer of the module should be responsible for doing so (which it appears you are). However, I personally would rather there be code written and contributed, even if it needs spiffying, rather than code not code written and contributed because it's too much of a pain to deal with the red tape. Modules can be improved incrementally to include better docs, better usability, etc. And newbies can also help here by providing suggestions from their point of view -- the people who need better docs and better usability. :)

We don't stop people from contributing code if they don't conform to coding standards. We provide the coding standards as a guide. Similarly, I think a document outlining, "Recommended documentation practices for new modules" would be a very valuable tool. But it needs someone to write it, not talk about writing it. ;)

dgtlmoon’s picture

I don't think this issue has been explored enough to even begin writing documentation for this, this submission is still open for comment.

There are most likely issues with this that both you and I haven't thought of yet, i'm curious to see what else people can bring to the fold

dww’s picture

Title:Modules should not be published on until they meet a minimum documentation requirement» Find ways to help maintainers and contributors make better documentation for modules. module» Other

#5 is so full of good ideas, it desperately needs to be turned into a handbook page somewhere prominently in the section about how to contribute (or the howto maintain a project on, perhaps).

That said, if it weren't for the useful discussion happening here, I'd mark this "won't fix" in terms of the actual request as titled and explained in the original post. I totally support the intention, but the proposed implementation (re-introducing a project publishing workflow, which includes remaining unpublished until someone decides it's well enough documented) is unworkable, IMHO.
a) The d.o maintainers are already stretched way too thin as it is -- who's going to do all this auditing and approving?
b) I'm with webchick on not putting up too many barriers to contributing something.
c) I'm also with webchick on the idea that lots of people could potentially contribute to the documentation efforts for a module, not just the original developer (though the developer obviously has certain responsibilities and abilities that others will not).
d) Short of getting workflow.module into core or installed on (neither of which is likely, anytime soon) this would involve a bunch of hacking to the project.module that I can't possibly imagine anyone paying for, and I'm certainly not volunteering to write it.

Also, keep in mind that the whole SoC effort on project quality metrics could probably include some metrics on the quantity and quality of documentation, which could help with this problem...

Therefore, I'm changing the title for this issue and moving the focus of the discussion away from a project publishing workflow onto the more general problem being addressed. dgtlmoon, hope you don't mind.

Thanks, folks.

dman’s picture

Totally agree with the topic change :)

I think we should

  • Simply hang a new page off of called "Documentation Standards"
    (or conventions<.em> or requirements or recommendations - whatever)
  • Start with whichever of the points in #5 everybody agrees with, dividing them into "minimum requirements" and "best practice recommendations"
  • Add any more suggestions anyone can add. ...The proper content and formatting of a README for example.
  • Put it out there and point at it a lot, encouraging module maintainers to encourage contributors to take it onboard alongside the Drupal code standards.

Even now, substandard code doesn't get automatically rejected by the system if it's got its whitespace wrong, but Maintainers are within their rights to reject patches that are not pretty enough according to 'coding standards'.
If we can just get these rules written down, then everyone will know whats expected... and is welcome to join in.

I'd like to kick off just making that page - but I'd like a little more buy-in from the big coders that my summary of what is reasonable help documentation is on track with the majority.

Those that care will notice that the modules I work on are really really heavily documented, often overpowering the code itself. This of course can be a hinderance in itself ;)

dgtlmoon’s picture

Sounds great, lets make the documentation page highly visible from the top of the coding standards page

it's interesting if you look at a lot of the README.txt's that come with modules, a few seem to have some structure
actually i think imagecache (despite what was mentioned in a recent drupal podcast) is a *good* example of what you can get away with at a minimum amount of documentation

- paragraph or two at the top describing what the model does ( "expected behaviour" )
- some usage text
- how to implement it

Imagecache is a dynamic image manipulation and cache tool.
It allows you to create a namespace that corresponds to a set
of image manipulation actions. It generates a derivative image the
first time it is requested from a namespace until the namespace or
the entire imagecache is flushed.

goto  Administer -> Site Configuration -> Image cache
create a ruleset,
add some actions to yoru ruleset,

add a
print theme('imagecache', $ruleset_namespace, $image['filepath'])

additionally the workflow module's README.txt is excellently documented, another good example.

maybe we should add a README.txt example to the node_example module , actually thinking along those lines the node_example is writen from the perspective of showing someone how to do some modular functionality, instead of writing a module that is maintainable by others in the community - if you catch my drift

halftone’s picture

I think one thing that could make life a lot easier would be if each project were to maintain a reasonably fully annotated listing of code for each release version, as a page. This would be enormously helpful for people like me (probably the vast majority of users) who are interested and want to understand, but are too inexperienced to be able to read difficult code without a bit of prompting.

I have been struggling with certain aspects of image.module (and the associated image_gallery module) for over a year. I feel like a snail crawling over a Swiss watch, trying to figure out what, why and how simultaneously.

There is nowhere I can ask, it would be meaningless (and would no doubt be irritatiing) if I posted questions about individual functions and what's going on inside them. I find this frustrating and I can't be the only aspiring Drupaller who has thought they understood what some bit of code did, gone ahead and modified it only to find I'd changed something else entirely, or nothing at all.

I'm not suggesting hooks to Drupal functions be annotated, the API docs already provide brief summaries. They're enough; I can then go and read the code with some idea of what the function is supposed to achieve. It's brief summaries for module-specific code, some brief clue what each custom function does and why and the logic flow within them, that would be useful.

Nor am I suggesting modules be bloated by endless comments, just that for people who are stuck, there be a page listing somewhere -- preferably with the ability to discuss how and why with peers.

I realise this goes against the grain of 'if you don't like it, fix it yourself' and I would if I could. Maybe eventually I will be able to. But as a direct result of my dimwitted attempts to 'enhance' things I didn't understand properly I have already very publically shared a completely broken solution, which is frankly embarassing. Appearing an idiot is a deterrent to sharing.

Sure, it's ungrateful to ask developers to do more than they already do, and it's certainly not their job to educate me, but the developers (presumably:) know better than anyone else. I'm guessing, but I would imagine a lot of developers do comment code like this whilst they're working on it, then strip it out for release. Just a few of lines of de-obfuscatory comment above each tricky bit would be a really useful lightbulb that would help people to help themselves and others.

Boris Mann’s picture

From the last comment, it would be fantastic if we actually maintained for ALL of contrib. Issue filed here:

halftone’s picture

Thanks. All good stuff, but more than a hint of Drupal Neverending Story Syndrome that relies on lots of things happening first, each of which relies on other things happening first, and so on, then someone will start rewriting it before its finished because core just got upgraded and off we go again.:)

I'm not really cynical - it would be lovely to just drill into anything from the Devel module - but developers who are sophisticated enough to use such a tool and engaged enough to be up to their elbows in CVS, probably don't need it all that much. They can read and write hard code! It just saves them time,

Which is good but it's the armies of halfwitted wannabees with 'L' plates, like me, who take up far too much of their own and other peoples' time being stuck. I don't want to be a user, I actually want to contribute! A plea to module developers to please, please stick a copiously-commented module listing up somewhere is a request for a whole different thing, a teaching aid, not a development tool like Though it would serve the purpose of a not-very-slick reference until the api stuff can get built. I think it would pay enormous dividends.

Boris Mann’s picture


A plea to module developers to please, please stick a
copiously-commented module listing up somewhere is a request for a whole
different thing, a teaching aid

You are looking for example modules. See

dman’s picture

Yeah, fair call. I don't think 'copiously' commented or even explicitly annotated code is appropriate for folk who are actually getting their hands dirty in code. It's not the job of a module writer to help bring the 'inexperienced' up to speed with concepts - code comments are for peers.

Inside modules, I see maybe three classes of functions

  1. Hook implementations - minimal documentation needed, but a reference back to the original is appropriate. Docs there should be a little more verbose than average.
    Theme implementations also.
  2. General, public, semi-api functions - usually only a few of these, published by core packages. A call like taxonomy_node_get_terms() is useful for programmers to know about. Good docs here are good, and where attention to detail would pay off. Docs there are for folk who want to understand how to use, and work with the module.
  3. _private and 'helper' functions used for structuring a modules internals (sometimes in secondary inc libraries). - If the module maker has under-commented those funcs, too bad. If a coder is looking at the code hard enough to want to mess with these things, they probably have to grok the entire thing first before messing with a bit like this. Docs here are for maintainers and actual coders, who (hopefully) will read the source as easily as any prose around it. Contextual 'de-obsfucation' comments , notes-to-self, excuses for doing something the long way and 'gotcha' workaround warnings you may be lucky enough to find there are simply a result of good overall programming practice.

Still, if the code isn't clear enough in the first place, no amount of extra documentation will make it better. Especially if it's not there in the file itself.
There's a dozen books on code style guidelines, and these should be followed before layering on docs to try and make wonky code look good.

In my experience however, every time I open up Drupal code, even contrib modules, I am pleasantly surprised.

  • very few functions are more than a screen long, those that are are simply repetative (like menu declarations or 'switch' type actions')
  • the methodologies are reasonably consistant across different authors (!) thanks to the example modules and good practices demonstrated in core.
  • Most functions DO have doc-blocks, even if only a subset of these bother with the full @param @return boilerplate. Useful var names are usually enough.
  • I do leave most of my debug notes in the code. I resist the urge to strip it out because I know that even the fact that I had to set a # drupal_set_message("node title is now $node->title") note there is useful for anyone who comes after to uncomment and see.

Coming back to annotations, I do like the user-supplied examples for how to use a specific function, and if that's what's halftone is looking for, I can sorta see why. However that's the end-user documentation for an entire language, not maintainer's notes for a single bit of functionality. Some areas of Drupal (views, form API, theming, and those that are intended as a base for others to build on - like the links package or jstools) do require, and have, deep end-user docs. This approach is simply not appropriate for one-job modules.

To be constructive, and get out of the wishlist mode folk are in -

Please enunciate, in the form of clearly worded documentation, exactly what you want to see from documentation

What, that's not already covered in the comment formatting guildelines and the coding standards do you want to see added to the list above as instructions for the coalface coders?
Keping in mind that there is no such thing as 'enforcement' coming out of this, just a set of best-practices for people to aim at.

Without a "here's what I think coders should do" constructive suggestion or three, the complaints that docs are insufficient are themselves just non-productive. And just saying "Do it more better" is not what I mean. Be specific and add a few more bullet-points to my list!

The api.module already exists and can be installed on your own site with a minimum of trouble, and will generate a full book-load of browsable, fleshed-out, cross-referenced docs for the code you want to investigate. Using this tool today does not rely on anyone else doing anything else. The 'lets publish it all' idea is a separate infrastructure proposal that Boris intentionally branched from this thread.

If you are intending to be reading or writing module code at all, devel.module, api.module, and coder.module are all good (possibly vital) tools to have on your dev site. They help you to help yourself. (Please suggest others that you cannot do without)

dww’s picture

Right on, dman. I say you start your documentation standards page with your ideas from #5, and let people comment on the page if they want to add anything. You (and doc team folks) can fold the comments into the body as appropriate. Furthermore, if there are any of the good practices you said in #15 that are not already expressed in the commenting standards page, please add them. In fact, I just added the "documentation maintainer" role to your account. ;)

Re: your list of useful developer modules from the end of #15, if it was better loved, I'd add the Database administration module. Sadly, it's low on my personal co-maintainer list, and the primary maintainer is absent for months at a time. But with more upkeep and care, it would be a very useful module for developers so they don't have to view or manipulate the DB outside of the Drupal site to understand the schema and see what's going on with the data. If anyone else wanted to join me as a co-maintainer, post an issue in its queue about it.


dman’s picture

OK, I guess that promotion counts as what I was looking for when I said I was hoping for "buy-in from the big coders".
Thanks heaps, I'm looking forward to folding a few comments into the handbook pages as I see them..

So, here's the first pass at this page of recommendations. Now bearing only a passing resemblance to my original bullet-points. Plus heaps more.

I realize that some of it may be tainted by personal opinion/preferences, so any feedback is welcome.

Does anyone have a favorite link to an online "How to write good documentation" article? I have respect for what I learnt from Code Complete but I have only the hard-copy.

I plan to add a child page with an example README. Does anyone have sugestions about the appropriate use of ASCII layout?




and section headings etc? Imagecache is clear, but not extensive. Any fuller ones? I've seen a lot of variants.

ax’s picture

> Axel Kollmorgen maintained an external mirror [of doxygen
> documentation for the contrib repository] ... for a while. It seems
> the contrib section has been culled. Probably due to space. :(

it had been culled because doxygen crashed over the size of the repo. it is up again with a new doxygen version that can handle the contrib repo.

drupey’s picture

I agree with the "Drupal Module Documentation Recommendations" except for one point - a screenshot should be mandatory for all modules for display next to the modules' descriptions on the web site (as is done with some of the themes already).

Even for non-graphical modules, just a logo or something to put there suffices, but without making some sort of graphic mandatory, unfortunately, you're just not going to get much of any.

The Vanilla forum software requires this of their uploaded modules, and there are no problems with it.

Reading the descriptions of some of the modules on Drupal's website, it's as clear as mud what exactly the module does and what it will look like running. I've installed modules and not even been sure if they're working properly because I don't know what proper looks like.

A picture is worth a thousand words, and a screenshot is a very, very easy picture to make.

Would this fit in with the minimum requirements section?

(and was that enunciated well enough?) ;)

Michelle’s picture

I agree that it should be encouraged, but not manditory. And let's not encourage it until we find a way to not have module screenshots show up on the module teaser list.


dgtlmoon’s picture

Maybe just voting on a module, and then a filter so it only shows modules that have atleast 1 vote? might help to keep a lot of noisey/unused/unusable modules out ?

dww’s picture

@dgtlmoon: That seems off topic for this issue. You should check out instead if you want to advocate for that. ;)

dgtlmoon’s picture

@dww: aaah neet, quality metrics, cheers!

Wolfflow’s picture


a newby that is not english native but strong motivated to learn how to use, implement, test, learn to make themes for Drupal and give back to Drupal community. If readme.txt files are easy to understand. someone like me could really do a good translation Job (Italian and German) and so help to expand the ***Great Drupal*** CMS.

Thank You all for your engagement.

rooey’s picture


I worry that enforcing immediate documentation requirements may deter some developers from starting their projects - the drupal infrastructure provides great mechanics to get started.

Perhaps it would be better to "move" such projects to an incubation section of - for projects in their infancy. This allows those potential projects the exposure they might need, and gives visibility to the rest of the community.

rooey’s picture

From the last comment, it would be fantastic if we actually maintained for ALL of contrib. Issue filed here:

That would be VERY nice - and would encourage folks to more closely follow the requirements for this.

sun’s picture

re: #10: An increasing list of modules uses an enhanced documentation template for README.txt and CHANGELOG.txt. Both files should be the bare minimum for projects listed by default on d.o.
The most advanced but still compact README.txt I know is

dman’s picture

Status:Active» Fixed

New discussion on README.txt over here.
I'll call the basic issue here fixed enough, there's never a final complete point for this. Improvements always possible.
Any remaining issues that have been overlooked from this thread can be done in new issues.

Morbus Iff’s picture

Anonymous’s picture

Status:Fixed» Closed (fixed)

Automatically closed -- issue fixed for two weeks with no activity.