Editing module pages on drupal.org

We encourage users to post events happening in the community to the community events group on https://www.drupal.org.
Mindy's picture

I tried searching, but I couldn't find the answer. Forgive me if I'm posting in the wrong place...

I see that I can edit handbook pages. I'm wondering why I can't edit module pages. Many times I've found a module on drupal.org and the module's page is less than stellar. It would be great if I could edit them to help make them easier for others to understand. Since there is revisioning, I don't see the harm (though perhaps an approval workflow moderated by the module's maintainer might be better). Who IS allowed to edit a module's main page?

Comments

Work with the maintainers

rfay's picture

People with CVS commit access to a project have permissions to edit a project (module/theme/install profile/etc) page. So you really need to file an issue explaining what to change. That is kind of an awkward way to go about it, isn't it. And it would be a nice thing if you could help with a module page in an easier way.

It seems like module

trevjs's picture

It seems like module maintainers would appreciate the contribution in most cases. It is too bad you can't submit a "patch" to their documentation. Or, what? I suppose you could post a text file with your changes, or additions. How do people usually do it?

I don't think people usually

arianek's picture

I don't think people usually do this at all to be honest! But indeed, I bet most maintainers would be happy to have help in that respect. As rfay pointed out, there's not really a way to do this, so my best suggestion would be to write up the changes and post them as an issue in the module's queue. The maintainers will see it there, and then can go back and forth with any changes, then modify the text themselves.

You can often contact the developer directly

Cliff's picture

Click on their name and you will go to their profile page. If they accept messages (not everyone does), you can send them a note asking if they're interested in getting editorial help. If they are, then work with them to figure out the best way to convey your edits to them.

I doubt many developers will turn down an opportunity to make the information about their modules clearer and more complete. Some might be too busy to deal with it, but even those will probably appreciate the offer.

Please use the issue queue

jhodgdon's picture

It is much more polite to use the issue queue for this sort of thing rather than contacting the module maintainer via email. Besides which, many modules are maintained by a team, and the issue queue is the central place for communication on issues related to the module and its documentation.

Adoption

Mindy's picture

From a Drupal adoption perspective, you would think that the friendliness of drupal module pages deserves more attention. There are certainly barriers to Drupal adoption, and one of them would be the relatively chaotic modules environment. Just sayin'...

I agree!

Cliff's picture

Wholeheartedly! And I'll bet most of the module developers would say that they did the best they could with the time available but would greatly appreciate help making their page better. A few of them won't have the time to review edits to their content, so we'll have to be sensitive to that.

Also, we need some way to index modules better. Most of the chaos takes hold well before you get to a module's page. It's in figuring out which 12 modules are even related to your need and then trying to piece together relevant information about how well they work, what else they do, and whether they're even up to date. We might ultimately need a better IA for modules and a redesign of the standard module page to reduce that chaos to a tolerable level.

There's an issue...

jhodgdon's picture

I proposed an IA and some better organization for modules a while back:
http://drupal.org/node/495418

You might check that issue out and/or comment on it.

Cliff, fwiw those sorts of

arianek's picture

Cliff, fwiw those sorts of changes are part of the d.o redesign plans. From what I understand, there'll be Solr search on the modules and themes pages, as well as better categorization.

open-source motivations

Mindy's picture

Yeah, module developers have enough to worry about. I would guess they're more excited about writing slick code than about writing well-written module pages or documentation. So, as much as possible, the community should create an environment that puts them in their happy place. And the happy place for us documentation-types (at times, at least) is when we see a page that's hard to understand and feel like we could help others understand it better. It's all about putting open-source contributors in their happy places! :)

Cliff, I couldn't agree more about the module chaos. Some way to know the difference between the dependability of a module like Views vs. something that was just whipped out there and not well-tested. Digging into the stats and the issue queue is not the most user-friendly way of evaluating a module. And I would think that hurts Drupal adoption.

I would love to arrive at a module page and see some kind of rating that tells me just how dependable the community feels the module is.

Ratings have mixed blessings

Cliff's picture

So, as I understand it, they're not done at drupal.org. However, there is an unrelated site called drupalmodules.com that does just that.

Obviously, there's a need!

The rating discussion has been beat to death

rfay's picture

Yes, the whole rating thing has been discussed ad nauseum. Not sure why we've never gotten it done. I think it got deadlocked in community discussion. But if you look, you'll find 10,000 discussions/comments.

Create a handbook page

rfay's picture

One thing I should have mentioned earlier on: In any nontrivial module, the "how-to" and such should really be in a handbook page, and everybody can then edit it.

So the easiest thing to do with a module maintainer is to create a new module page for them, put great info there, and then help maintain it.

Just a few thoughts to

trevjs's picture

Just a few thoughts to add:

-It seems most complaints about documentation are actually related to contrib modules
-It also seems like most problems people have are related to contrib modules
-Where as books on drupal are good at covering the basic overview, this is one area that a community documentation process would be more effective

Also, adding to what Cliff is saying about indexing, when you google a module it gives you the link to the module page, but underneath it gives you links to everything but the documentation (this is probably because of where the docs are on d.o.). Furthermore, on the module pages, the docs link is all the way at the bottom. My thoughts are that usage statistics and the docs links should be right up at the top.

But ya know. It is how it is. Something to keep in mind though. We might not be able to do anything about it now, but maybe in the future.

FYI - jhodgdon and i did

arianek's picture

FYI - jhodgdon and i did sneak in a standard by way of the D7 help system upgrade ;-) so if contrib module maintainers follow the help standard set here: http://drupal.org/node/632280 there will always be a link from the module's help page back to the main page for the module in the online handbook.

it'd be great to get a similar standard for project pages, but that would be a much bigger initiative.

Documentation

Group categories

Event type

Post type

Group notifications

This group offers an RSS feed. Or subscribe to these personalized, sitewide feeds: